Solução de problemas no Jitterbit Harmony

Este guia aborda problemas comuns de solução de problemas na plataforma unificada do Harmony (integração, automação, gerenciamento de API, EDI e desenvolvimento de aplicativos), organizado por funcionalidade para que você possa encontrar e resolver problemas onde quer que surjam. Expanda a lista abaixo para verificar todas as entradas nesta página ou use a função de busca do seu navegador Control + F (Windows ou Linux) ou Command + F (macOS) para procurar uma mensagem de erro ou sintoma específico.

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

Administração da plataforma
Integração e automação

Gerenciamento de API
EDI
Desenvolvimento de aplicativos

Etapas de diagnóstico

Verificar os logs de operação

No Console de Gerenciamento, abra a página Runtime e revise a entrada de log da operação afetada. O status e as mensagens de log são o indicador principal da causa. A página Runtime lista todas as operações, incluindo aquelas executadas diretamente e as acionadas por uma API (mostradas na coluna Log Type como Custom API, Proxy API ou OData API), portanto é o lugar para começar na maioria dos problemas de runtime.

Verificar os logs de API

Para detalhes específicos de API, abra a página API Logs no API Manager. Ela mostra dados de solicitação e resposta de cada chamada de API (código de status HTTP, tempo de resposta, URI de solicitação, IP de origem) e, quando habilitado, rastreamentos de debug e verbose. Os logs de operação para operações acionadas por API também aparecem aqui, ao lado da página Runtime.

Verificar os logs do agente

Para ambientes executados em agentes privados, revise os arquivos de log do agente para erros de conectividade, recursos e sincronização. Consulte logs do agente para localizações de arquivo.

Verificar o status do sistema Harmony

Se um problema parecer afetar todas as operações ou todas as APIs em vez de um único workflow, verifique trust.jitterbit.com e a página de problemas conhecidos antes de investigar mais.

Administração da plataforma

Esta seção aborda problemas no nível da plataforma Harmony: autenticação, gerenciamento de usuários e ambientes, e implantação de projetos.

Sintoma: Os usuários não conseguem fazer login no portal Harmony.
Resolução:
- Verifique trust.jitterbit.com para interrupções ativas da plataforma.
- Limpe o cache e os cookies do navegador e tente novamente, ou use uma janela anônima ou privada ou um navegador diferente. Dados de sessão em cache desatualizados podem fazer com que o portal volte à página de login ou falhe ao carregar após o login.
- Se o SSO estiver configurado, peça a um administrador para verificar a configuração do SSO. Consulte Harmony SSO.
- Confirme se a conta do usuário está ativa e não foi desativada na página Gerenciamento de Usuários do Console de Gerenciamento.
- Se o login ainda falhar após essas verificações (por exemplo, uma redefinição de senha não for concluída ou a conta aparecer como inativa apesar de estar ativa), entre em contato com o suporte Jitterbit.

Conta bloqueada após tentativas de login falhadas

Sintoma: Um usuário não consegue fazer login após inserir credenciais incorretas. Seu status na página Gerenciamento de Usuários do Console de Gerenciamento aparece como Inativo.
Possível causa: Após 5 tentativas de login falhadas consecutivas, a conta é bloqueada por 30 minutos.
Resolução:
- Aguarde 30 minutos e tente novamente com as credenciais corretas.
- Alternativamente, use o link Esqueci minha senha na página de login do portal Harmony para redefinir a senha e limpar imediatamente o bloqueio.

Usuário não consegue acessar um ambiente ou seus recursos

Sintoma: Um usuário consegue fazer login, mas não consegue ver um ambiente, não consegue implantar nele ou está faltando recursos esperados.
Possível causa: O acesso ao ambiente é controlado pelas funções atribuídas ao usuário.
Resolução: Um administrador deve conceder à função do usuário o acesso ao ambiente apropriado no Console de Gerenciamento. Verifique as funções atribuídas ao usuário e as permissões concedidas a essas funções.

Variáveis de projeto não transferidas durante a promoção de ambiente

Sintoma: Após transferir um projeto para outro ambiente, alguns valores de variáveis de projeto estão faltando no destino ou não são os valores esperados.
Possível causa: Se o valor de uma variável de projeto é transferido depende da opção de transferência usada e suas configurações de variável:
- Em uma transferência completa de projeto (a caixa de diálogo Migrar), a primeira transferência usa como padrão Migrar todos os valores de variáveis, mas transferências posteriores usam como padrão Selecionar valores de variáveis para migrar, o que exclui qualquer variável cujo valor foi alterado. Uma variável que não está incluída e ainda não existe no destino é transferida sem um valor.
- Em uma transferência seletiva, a etapa Configurar variáveis controla quais variáveis são transferidas, e a opção Incluir valor padrão determina se o valor de destino é substituído pelo valor padrão do projeto de origem.
Resolução:
- Na caixa de diálogo Migrar, escolha Migrar todos os valores de variáveis ou selecione Selecionar valores de variáveis para migrar e adicione as variáveis que deseja transferir para Incluir.
- Em uma Transferência Seletiva, na etapa Configurar variáveis, selecione as variáveis a transferir e defina Incluir valor padrão conforme necessário.
- Alternativamente, defina os valores de variáveis corretos para o ambiente de destino no Studio após a transferência. Faça essas alterações no Studio em vez da página Projetos do Console de Gerenciamento para que sejam registradas no histórico do projeto.

Alternar o grupo de agentes de um ambiente falha com erro de versão mínima de agente

Sintoma: Alterar o grupo de agentes associado a um ambiente no Console de Gerenciamento falha com:
```
MIN_RQRD_AGENT_VERSION_NOT_MET_CODE
```
Possível causa: Um ou mais agentes no grupo de agentes de destino estão executando uma versão abaixo da versão mínima de agente que o ambiente requer, então a alternância é rejeitada. A versão mínima é definida pelos projetos implantados no ambiente: se algum projeto implantado exigir uma versão de agente mais recente do que a fornecida pelo grupo de destino, a alternância falhará. Isso pode ocorrer com um grupo de agentes privados, cujas versões de agente você gerencia, ou com um grupo de agentes em nuvem, que a Jitterbit atualiza em um cronograma escalonado (sandbox antes de produção), então um grupo de agentes em nuvem de destino pode estar brevemente uma versão atrás durante um lançamento.
Resolução:
- Grupo de agentes privados: Na página Agentes do Console de Gerenciamento, identifique cada agente no grupo de destino e atualize cada um para uma versão que atenda ou exceda a versão mínima necessária do ambiente (consulte Atualização contínua). Em seguida, tente novamente alternar o grupo de agentes do ambiente.
- Grupo de agentes em nuvem: Os agentes em nuvem são atualizados pela Jitterbit e não podem ser atualizados manualmente. Mantenha o ambiente em um grupo de agentes que já atenda à versão necessária ou tente novamente a alternância após o grupo de agentes em nuvem de destino ter sido atualizado.

Design Studio: usuários de SSO fora da região da organização não conseguem fazer login

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

Teste de configuração de SSO bloqueia a conta do provedor de identidade

Sintoma: Um administrador fica bloqueado em sua conta do provedor de identidade ao testar uma configuração de SSO no Console de Gerenciamento.
Possível causa: Cada clique em Testar Configuração abre o portal de login do provedor de identidade e conta como uma tentativa de autenticação contra a política de bloqueio do IdP. Clicar no botão repetidamente pode disparar o bloqueio de conta do IdP.
Resolução:
- Limite o número de tentativas de teste em uma única sessão.
- Se ficar bloqueado no provedor de identidade, siga o processo de recuperação de conta do IdP antes de tentar novamente o teste de configuração de SSO. Consulte Configurar SSO para obter as etapas completas de configuração.

Política de lista de permissões de IP bloqueia um administrador

Sintoma: Você perde o acesso ao portal Harmony imediatamente após outro administrador alterar os intervalos em Ativar intervalo de IP da lista de permissões.
Possível causa: A política Ativar intervalo de IP da lista de permissões requer que o endereço IP de cada usuário esteja incluído no intervalo configurado. Uma mensagem de validação impede que um administrador salve um intervalo que exclua seu próprio IP atual, mas não verifica os endereços IP de outros administradores. Se a alteração de outro administrador excluir seu IP, você será bloqueado imediatamente.
Resolução:
- Peça a outro administrador cujo IP esteja dentro da lista de permissões que atualize ou desative a política, ou entre em contato com o suporte da Jitterbit.

Alterar subdomínio de API quebra integrações de API existentes

Sintoma: Após alterar o subdomínio de API de uma organização no Console de Gerenciamento detalhes da organização, as chamadas para as APIs publicadas da organização de clientes e integrações existentes começam a falhar.
Possível causa: O subdomínio de API forma a URL base da API para cada API na organização, então alterá-lo reescreve a URL de todas as APIs do API Manager da organização. Qualquer cliente ou integração ainda chamando a URL anterior falhará.
Resolução:
1. Nos detalhes da organização, observe a URL base atualizada mostrada no campo Visualização de URL base da API.
2. Atualize todas as integrações, aplicativos cliente e configurações de webhook que fazem referência à URL base da API anterior.
3. Para evitar interrupções, planeje alterações de subdomínio durante uma janela de manutenção e notifique todos os consumidores de API com antecedência.

O acesso do usuário externo ao API Portal expira em um momento inesperado

Sintoma: O acesso de um usuário externo ao API Portal expira mais cedo ou mais tarde do que o administrador esperava com base na data configurada.
Possível causa: O acesso do usuário externo expira às 23h59 da data de expiração selecionada no fuso horário local do usuário externo. Se o usuário e o administrador estão em fusos horários diferentes, o horário de expiração efetivo difere do que o administrador vê na tela de configuração.
Resolução:
- Ao definir uma data de expiração para um usuário externo na página Gerenciamento de Usuários, leve em conta o fuso horário local do usuário ao escolher a data.
- Para estender o acesso, edite a data de Acesso Expira do usuário antes da data atual expirar.

Alterações de ambiente não refletidas em aplicações Harmony

Sintoma: Após fazer alterações em um ambiente no Console de Gerenciamento, as alterações não aparecem no Studio ou em outras aplicações Harmony.
Resolução: Faça logout do portal Harmony e faça login novamente. As alterações de ambiente podem não se propagar para outras aplicações Harmony até que a sessão seja atualizada.

A configuração de SSO requer clientes WMC e Studio

Sintoma: A autenticação de logon único (SSO) do Harmony falha ou funciona apenas para algumas aplicações Harmony após configurar um provedor de identidade SSO.
Causa: O SSO do Harmony requer que duas aplicações cliente separadas sejam configuradas no provedor de identidade: WMC (para o portal Harmony e todas as aplicações web) e Studio (para o Design Studio). Configurar apenas um cliente deixa a outra aplicação sem suporte a SSO.
Resolução: Configure as aplicações cliente WMC e Studio na gaveta Configurar SSO, mesmo que não use o Design Studio. Para clientes BMC, apenas WMC é necessário.

Lista de bypass de SSO: membros da organização existentes não podem ser adicionados diretamente

Sintoma: Adicionar um membro atual de uma organização habilitada para SSO à sua lista de Bypass de SSO falha, ou o usuário ainda não consegue fazer bypass de SSO após ser adicionado.
Causa: Um usuário deve ser adicionado à lista de Bypass de SSO antes de ser adicionado à organização. Um usuário que já é membro da organização, portanto, não pode ser adicionado à sua lista de Bypass de SSO diretamente.
Resolução:
1. Remova o acesso do usuário à organização.
2. Adicione o endereço de email do usuário à lista de Bypass de SSO.
3. Adicione o usuário novamente à organização.

SSO não pode ser habilitado: usuário pertence a várias organizações

Sintoma: Habilitar o logon único (SSO) do Harmony para uma organização Harmony falha com:
```
SSO_CANNOT_BE_ENABLED_FOR_MEMBERS_ASSOCIATED_WITH_MULTIPLE_ORGS
```
Possível causa: Um ou mais usuários na organização também são membros de outras organizações Harmony, como organizações de avaliação ou organizações do Cloud Data Loader.
Resolução:
1. Revise a lista de usuários da organização no Console de Gerenciamento para identificar usuários que pertencem a mais de uma organização Harmony.
2. Para cada usuário afetado, escolha uma das seguintes opções:
  - Remova-os das outras organizações às quais pertencem (incluindo organizações de avaliação do Harmony ou organizações do Cloud Data Loader), ou desta organização, para que pertençam a apenas uma organização Harmony.
  - Para permitir que o usuário permaneça em várias organizações, adicione-o à lista de Bypass de SSO, que os exclui do SSO para que façam login com suas credenciais do Harmony. Como um membro atual não pode ser adicionado à lista diretamente, primeiro remova seu acesso a esta organização, adicione-o à lista de Bypass de SSO e depois adicione-o novamente.
Tente novamente a configuração de SSO após todos os usuários afetados terem sido removidos ou adicionados à lista de Bypass SSO.

SSO redireciona para login em loop sem erro

Sintoma: Um usuário que tenta fazer login no Harmony via logon único (SSO) (por exemplo, com Azure) é continuamente redirecionado de volta à página de login sem mensagem de erro.
Possível causa: Cache do navegador obsoleto ou cookies estão interferindo no fluxo de autenticação SSO.
Resolução:
- Limpe o cache do navegador e todos os cookies relacionados ao Jitterbit, depois tente novamente.
- Tente fazer login em uma janela de navegação anônima ou privada para contornar dados em cache.
- Tente um navegador diferente para descartar problemas de compatibilidade específicos do navegador.

Falha na exclusão de armazenamento do Cloud Datastore com erro "cannot be excluded"

Sintoma: A exclusão de um armazenamento de status ou armazenamento de chave do Cloud Datastore falha com:

Failed to delete storage: <storage name> - Storage with ID <storage ID> cannot be excluded because it contains items.

Resolução: Exclua todos os dados (como registros) no armazenamento antes de excluir o próprio armazenamento, depois tente novamente a exclusão.

Token de acesso não pode ser editado após seu ambiente ser excluído

Sintoma: Um token de acesso não pode ser editado ou copiado, mesmo que ainda apareça na página Access Tokens do Console de Gerenciamento.
Causa: Se o ambiente associado ao token foi excluído, você não pode mais editar ou copiar o token, embora ainda possa excluí-lo.
Resolução: Exclua o token e crie um token de acesso de substituição em um ambiente existente.

Expiração do token de atualização OAuth causa falha em operações conectadas

Sintoma: Operações que usam um conector autenticado com OAuth 2.0 de 3 pernas (3LO) deixam de funcionar após um período de tempo, com erros de autenticação como Connector could not retrieve the access token to be used in the HTTP call ou uma mensagem do provedor de identidade informando que o token de atualização foi invalidado ou já foi trocado. A conexão geralmente é bem-sucedida imediatamente após a autenticação e depois falha em uma execução posterior.
Possíveis causas:
- Uma Token policy na página App Registrations do Console de Gerenciamento tem Enable refresh token expiration ou Enable refresh token inactivity expiration configurado, portanto todas as operações dependentes dessa conexão falham em tempo de execução quando o token expira.
- A conexão ficou ociosa por mais tempo do que o tempo de vida do token de atualização do provedor de identidade. Conforme descrito nas Notas importantes do 3LO, tokens de atualização são usados apenas quando uma operação requer acesso ao endpoint: o conector renova o token de acesso reativamente quando uma operação é executada, não através de um processo de background ou de um token refresh agendado independente. Se nenhuma operação acessar o endpoint dentro do tempo de vida do token de atualização (que alguns provedores definem tão curto quanto 24 horas), o próprio token de atualização expira e a cadeia de tokens se quebra, mesmo quando Enable rotating refresh token está selecionado.
- O mesmo registro de aplicativo e credenciais de usuário são usados para 3LO em mais de um projeto ou endpoint. Com Enable rotating refresh token selecionado, cada atualização de token emite um novo token de atualização e invalida o anterior. Se as credenciais compartilhadas forem re-autenticadas ou atualizadas em um lugar, o token de atualização que as outras operações estão mantendo é invalidado, portanto essas operações falham.
Resolução:
- Se a causa for uma configuração de expiração de Política de Token, analise a política do registro de aplicativo afetado, renove o token de atualização usando o fluxo de autenticação do conector e ative Receber Notificação de Expiração nas configurações de conexão para receber aviso prévio antes do token expirar novamente.
- Se a causa for um período ocioso, certifique-se de que uma operação que usa a conexão seja executada dentro do tempo de vida do token de atualização. Agendar uma atualização de token autônoma para manter um token ativo ou redefinir um relógio de inatividade não é suportado (consulte as Notas importantes de 3LO): o token é renovado apenas como efeito colateral de uma operação que realmente acessa o endpoint. Para usar esse comportamento suportado, adicione uma operação leve em um agendamento de operação recorrente que chame um endpoint simples em um intervalo menor que o tempo de vida do token de atualização (por exemplo, a cada duas horas), usando o mesmo conector e registro de aplicativo que suas operações principais. Essa operação faz uma solicitação real ao endpoint, portanto cada execução renova os tokens como parte do uso normal. Apenas uma operação desse tipo é necessária por registro de aplicativo. Se o provedor de identidade permitir, você também pode estender o tempo de vida do token de atualização.
- Se mais de um projeto ou endpoint compartilhar o mesmo registro de aplicativo e usuário, atribua a cada um seu próprio registro de aplicativo (ou usuário) para que suas cadeias de token não se invalidem mutuamente e evite reautenticar a conexão compartilhada enquanto outras operações dependem dela.

API de Log de Auditoria: falha na recuperação de token quando TFA está ativado

Sintoma: uma solicitação à API do Controlador de Serviço do Usuário para recuperar um token de autenticação para a API de Serviço de Log de Auditoria retorna um erro.
Causa: quando a autenticação de dois fatores (TFA) está ativada para a organização, uma recuperação de token de solicitação única padrão falha. A TFA requer um fluxo de autenticação em duas etapas.
Resolução: siga o procedimento de recuperação de token TFA para obter o token de autenticação usando o fluxo de duas solicitações.

Falha ao adicionar um usuário externo com erro `409 conflict`

Sintoma: adicionar um usuário externo na página Gerenciamento de Usuários do Console de Gerenciamento falha com:
```
Failed to create new external user - 409 conflict error
```
Possível causa: um usuário com esse endereço de email já existe no sistema de usuários da Jitterbit, portanto o usuário externo não pode ser criado novamente, mesmo que o usuário não seja visível na organização de destino.
Resolução: entre em contato com o suporte da Jitterbit com o endereço de email. A conta existente pode precisar ser reconciliada ou reatribuída no nível da plataforma antes que o usuário externo possa ser adicionado.

A região da organização não pode ser alterada no local

Sintoma: uma organização precisa se mudar para uma região Harmony diferente (por exemplo, de NA para EMEA) por motivos de residência de dados ou conformidade, mas não há configuração para alterar a região de uma organização existente.
Possível causa: a região de uma organização é fixa na criação. O Harmony não suporta alterações de região no local.
Resolução:
1. Crie uma nova organização Harmony na região de destino.
2. Exporte cada projeto de integração da organização de origem e importe-o para a nova organização.
3. Na nova organização, reconfigure as configurações específicas do ambiente, conexões, agendamentos, variáveis de projeto e perfis de segurança.
4. Atualize todos os clientes externos, integrações ou configurações de webhook para apontar para as URLs de API da nova região.
5. Para uma migração coordenada, entre em contato com o suporte da Jitterbit ou Serviços Profissionais para planejar o cronograma e minimizar o tempo de inatividade operacional.

Integração e automação

Esta seção aborda problemas com a conexão a sistemas externos, transformação e processamento de dados, e execução de operações de integração, junto com os agentes que as executam.

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

Sintoma: Uma operação não é concluída conforme esperado. Ela permanece em estado Submitted ou Running e nunca progride, 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 o início, e não reflete necessariamente 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 Running 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 Harmony, então ela continua aparecendo como Running até expirar.
- O grupo de agentes está sob carga pesada e é lento para pegar ou atualizar operações enfileiradas.
- A operação está travada especificamente em Submitted: a mensagem de execução foi enfileirada, mas nenhum agente no grupo a aceitou, porque os agentes estão offline, não estão saudáveis ou não têm capacidade livre para aceitar novas operações (por exemplo, cada thread de trabalho está ocupada).
Resolução:
- Para agentes privados, confirme que o agente tem status Running na página Agents no Management Console, 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 brevemente, 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 atenuado reduzindo a taxa de requisições ou adicionando lógica de retry; um 429 do gateway de API em nuvem 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 posteriores do agente 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 na página Runtime do Management Console, na tabela de log de operação ou no status de runtime de uma operação na tela de design.
- Se a operação afetada é executada em um agendamento e nunca inicia, consulte Operações agendadas nã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 Jitterbit, pois esses casos podem exigir resolução no lado do servidor.

Nota

A configuração MaxOperationRuntimeSeconds na seção [ProcessEngine] do arquivo jitterbit.conf do agente privado apenas limita quanto tempo uma operação é executada após um agente ter começado a executá-la, portanto não tem efeito em operações ainda enfileiradas no estado Submitted. A configuração de operação Operation Time Out limita o tempo total de execução de uma operação, mas não pode ser limitada apenas ao estado Submitted, portanto reduzi-la para forçar um cancelamento rápido também cancelaria operações que ainda estão sendo executadas legitimamente. Para limpar operações presas em Submitted, restaure a capacidade e a saúde do agente para que as mensagens de execução enfileiradas sejam processadas, em vez de ajustar um timeout.

Operações agendadas não sendo executadas

Sintoma: Uma operação configurada com um agendamento de operação não é executada no horário agendado ou é despachada mas permanece em 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 entram em vigor 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á saturado de 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 execute operações agendadas no 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 na página Projects do Management Console, nas abas Operations e Schedules.
- Revise a configuração de agendamento, prestando atenção particular à configuração de fuso horário. Para 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 Management Console 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 Task Manager. No Linux e Docker, use o comando jitterbit status.
- Reimplante o projeto para forçar o agendamento a ser ressincronizado com o agente.
- Se operações estão presas em estado Pending, cancele-as pela página Runtime do Management Console e reinicie o serviço do agente.
- Se as falhas de agendamento se correlacionam com carga, reduza o número de operações de longa duração simultâneas. Em agentes privados, também revise o uso de CPU e memória e equilibre 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 é despachada mas depois trava em vez de nunca iniciar, consulte Operações presas em estado Submitted ou Running.

Dicionário ou variável global vazia 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 o 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 filha é executada em uma thread separada e a pai continua sem aguardar. 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 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 o comportamento equivalente em operações multi-thread em chunks, consulte Variable updates lost in chunked multi-threaded operations.
Resolução:
- Se a pai depende de 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ável global 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 tenha terminado; execute a operação de forma síncrona.

Falhas de conexão e autenticação

Certificado Salesforce: incompatibilidade de Subject Alternative Name (SAN)

Sintoma: Uma conexão Salesforce com uma sandbox ou uma org com Domínios Aprimorados ativados falha com:
```
Certificate for <url> doesn't match any of the subject alternative names
```
Possíveis causas:
- O certificado não inclui o MyDomain do Salesforce ou a URL da sandbox em seus Nomes Alternativos do Assunto.
- A caixa de seleção Sandbox nas configurações de conexão do Salesforce não está corretamente ativada.
Resolução:
- Inspecione as entradas SAN do certificado usando OpenSSL: openssl x509 -in cert.crt -text -noout. Confirme que a seção Nome Alternativo do Assunto inclui sua URL do MyDomain do Salesforce.
- Nas configurações de conexão do Salesforce no Studio, verifique se a caixa de seleção Sandbox está corretamente definida para sua org de destino.
- Se a URL do Salesforce estiver ausente dos SANs, regenere o certificado para incluir o domínio específico.
- Se a mesma conexão funciona em um grupo de agentes na nuvem mas falha em um agente privado, a causa pode ser uma extensão SNI ausente no handshake TLS do agente. Consulte Falha na conexão da sandbox do Salesforce com incompatibilidade de certificado.

Falha de conexão com 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: Este é um problema no nível do agente com as conexões de banco de dados interno do agente privado. Consulte Falhas de conexão TranDb no guia de solução de problemas 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 com TLS mútuo (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.
Possíveis causas:
- O usuário do sistema operacional que executa o agente Jitterbit não tem permissão de leitura para o arquivo de chave privada ou seus diretórios pai.
- Um módulo de segurança Linux como SELinux ou AppArmor está bloqueando o acesso do agente ao arquivo de chave privada.
Resolução:
- Certifique-se de que a conta que executa o agente Jitterbit tem acesso de leitura ao arquivo de chave privada e a todos os diretórios pai.
- Verifique se SELinux ou AppArmor está restringindo o acesso ao arquivo de 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 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 de 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 direcionar apenas a seção CDATA, toda a string XML que a contém pode ser substituída.

O exemplo a seguir é considerado inválido sem essas substituições:
```
{
  "name": "Jitterbit",
  "data": "<xml><content><![CDATA[<greeting>Hello, world!</greeting>]]></content></xml>"
}
```

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 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), portanto, 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 downstream (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, portanto, atualize o agente primeiro se estiver em uma versão anterior.

Caracteres especiais em esquemas JSON fornecidos por conectores

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 sublinhados (_). Ao usar processamento JSON legado (o padrão para projetos criados antes do Harmony release 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 fornece 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 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 log de depuração ativado:

Caracteres multibyte corrompidos em uma resposta grande do conector

Sintoma: Um caractere multibyte em uma resposta do conector JSON está corrompido. O texto corrompido mostra 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 antes na resposta não é afetado.
Possível causa: Nas versões do agente 12.8 e 12.9, 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 do agente 12.10 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. Usar um resulta em um erro de runtime:
```
Failed to initialize transformation "<transformation name>". Failed to expand the (source|target) tree for the path: <path to substitution head node>.
```
Esse erro também pode ocorrer por outros motivos, 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 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.).

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 runtime 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 quando executada.

Possível causa: Importar um arquivo de mapeamento que adicionou nós duplicados ao esquema de destino não aplicou a alteração correspondente à definição de 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.
Resoluçã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. Reimportar ressincroniza a definição de 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 alterações 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 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 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 retém o prefixo de namespace original, portanto o esquema é idêntico a 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 extra subelement 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 de resposta.
Resolução: Se for necessário 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 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 converte 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. Em contraste, um valor como "1string" produziria 1, já que o dígito inicial é mantido.
Resolução:
1. Verifique a definição de esquema do 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. Esse 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 de 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 desabilita transformações de streaming definindo 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 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 fazem referência a dois ou mais nós de loop de origem diferentes. Cada nó de loop de destino pode iterar sobre apenas 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 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 descarta 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) descarta 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 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 é 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 à esquerda e à direita dos valores de campo CSV por padrão. Registros que diferem apenas por espaços à esquerda ou à direita se tornam idênticos após a remoção 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 contorna 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 definindo uma variável Jitterbit em uma etapa de script anterior à transformação. Para transformações simples para simples, defina jitterbit.transformation.disable_normalization como true. Para transformações simples 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 com cuidado.
- Se os duplicados forem causados especificamente por diferenças de espaço em branco, defina jitterbit.source.preserve_char_whitespace como true em uma etapa de script anterior à transformação. Isso preserva o espaço em branco durante a análise para que os 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 e produzindo um valor incorreto no destino.
Possível causa: O campo de origem ou destino é implicitamente tipado 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 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 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 a jusante 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 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 uma etapa de script usando concatenação de strings e envie-o através de um conector HTTP v2 com um corpo de solicitação sem schema.

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 uma etapa de script anterior à transformação, defina $jitterbit.target.xml.include_null_xml = false para remover completamente da saída os nós com um valor nulo ou vazio. Se, em vez disso, 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 nulos 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 (BOM) UTF-8, 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, você também pode definir explicitamente a codificação de caracteres como UTF-8 antes da atividade de origem ser executada, por exemplo $jitterbit.source.text.character_encoding = "utf-8";. 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 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.
Possível causa: 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 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 uma 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.
Possível causa: ReadFile não é confiável com conteúdo de arquivo binário e geralmente 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 XML ou JSON UTF-8

Sintoma: Uma transformação que mapeia conteúdo de arquivo bruto lido com ReadFile (por exemplo, um arquivo EDI bruto) para um campo de destino XML ou JSON em 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: Corresponda 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 escrever 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 escrita para remover o arquivo existente.
- Alternativamente, use um nome de arquivo dinâmico que inclua um timestamp ou identificador único para evitar conflitos.

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

Sintoma: Um script usando DeleteFiles falha com um erro quando o caminho de origem ou diretório 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 falhar na 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 causar a interrupção de todo o script.
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 o payload JSON imediatamente antes da chamada GetJSONString para verificar a estrutura real e confirmar o caminho.

Limite de iterações do loop de 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çõ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.

`RunOperation` para de executar após 50 chamadas síncronas em um loop `While`

Sintoma: Após atualizar um agente 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 de retorno da função ou chame GetLastError. O log da operação mostra uma entrada identificando a operação sendo invocada quando o limite foi atingido.
Possível causa: A partir da versão 12.11 do agente, um limite no nível do agente (MaxSynchronousRunOperationCallsInLoop na seção [OperationEngine] do arquivo jitterbit.conf, 50 por padrão) limita o número de chamadas síncronas RunOperation, RunOperationFromProject e ReRunOperation feitas dentro de um único loop While; todos os três compartilham uma contagem cumulativa por loop. Quando o limite é atingido, cada chamada subsequente retorna false sem gerar um erro, portanto um loop que não verifica o valor de retorno continua iterando sem perceber que as chamadas posteriores não fizeram nada.
Resolução:
- Se o loop não verificar o valor de retorno, encapsule a chamada para que um limite acionado 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 da execução do loop, desde que as substituições por operação sejam permitidas (MaxSynchronousRunOperationCallsInLoopOverrideAllowed).
- Para aumentar o padrão em toda a plataforma, aumente MaxSynchronousRunOperationCallsInLoop na seção [OperationEngine] do arquivo jitterbit.conf.

Comparar uma string com um número produz 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 a ramificação errada é executada:
```
$value = "test";
If($value == 0, WriteToOperationLog("equal"), WriteToOperationLog("not equal"));
// logs "equal", even though "test" is not 0
```
Causa: Quando os dois operandos são de 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 em relação a 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 puder 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 de agente anteriores à 12.9, essa combinação não desmapeava o campo.
- Unmap é chamado de dentro do script invocado por RunScript, em vez de diretamente na própria expressão de mapeamento do campo de destino. RunScript retorna o resultado do script chamado como uma string em vez de propagar um sinal de desmapeamento de volta 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 forem ambos chamados diretamente na expressão de mapeamento do campo de destino, atualize para a versão 12.9 do agente ou posterior.
- Se Unmap for chamado de dentro do script invocado por RunScript, mova a chamada Unmap para fora do script chamado e para a própria expressão de mapeamento do campo de destino, por exemplo:
```
RunScript("<TAG>script:MyScript</TAG>"); If(<condition>, Unmap(), <value>);
```

`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 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 de transação explícito e 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 indefinida 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 é suportado apenas por 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, mude o endpoint de banco de dados para usar um driver JDBC em vez de ODBC.
- Se não for possível trocar drivers, recupere os 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 faz distinção 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 é suportado 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, mude 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 anterior à chamada AESDecryption para habilitar compatibilidade com OpenSSL 3.
- Alternativamente, substitua AESDecryption por AESDecryptionEx, que suporta OpenSSL 3 por padrão em versões de agente 11.42 ou posterior.

Variáveis de 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 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).
Possível causa: 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, 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 de projeto: Na configuração da variável de projeto, insira o valor a ser usado durante o teste 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), portanto em tempo de execução também atua como um fallback quando a variável não está definida. Consulte 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 script em si, antes da linha que a usa. Como uma variável global obtém seu valor da execução do script em vez da 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 é derivado em um script ou quando você não deseja 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 abrange tanto o método de pill de variável quanto o método de sintaxe inline para campos que não mostram um pill).

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, Cadeia de Conexão ou um endereço de servidor) definido como uma variável global ou de projeto. Testar um script executa apenas o script testado, portanto a variável ainda não recebeu seu valor em tempo de execução quando a função resolve a conexão. 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 de projeto retornam valores vazios durante testes de script e transformação.
Resolução: Antes da chamada da função, atribua temporariamente a mesma variável global ou de projeto seu valor real diretamente no script testado (por exemplo, $login = "value"; para uma variável chamada login), depois remova a atribuição antes de implantar a operação.

`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 aparenta não ter valor. A lógica downstream que depende da verificação de nulo se comporta de forma inesperada ou produz resultados incorretos.
Possível causa: JSON distingue entre um valor ausente ou explicitamente null e uma string vazia (""). Um campo definido como "" em JSON é uma string vazia, não nulo, portanto IsNull corretamente retorna false 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 true para strings vazias dependiam de um comportamento anterior que não é mais correto.
Resolução:
- Use IfEmpty para lidar com 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 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 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 com o número `0` retorna inesperadamente `true`

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 outra lógica que verifica zero produzem resultados inesperados.
Possível causa: Quando o Jitterbit Script compara valores de tipos de dados diferentes, tenta converter ambos os operandos para 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, 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 inesperados de ponto flutuante

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 é avaliado como 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, portanto a aritmética nelas pode acumular pequenos erros de arredondamento. A subtração que cancela a maior parte 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 computado.
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); // returns 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);
```

Funções de data retornam meia-noite em vez de um valor somente 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 somente de data (2026-01-01), o que pode quebrar a lógica downstream que espera o formato mais curto. CVTDate não é afetado.
Possível causa: Com a versão 12.8 do agente 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 somente de data, enquanto qualquer outra hora era preservada corretamente.
Resolução: Se a lógica downstream exigir um valor somente 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 passar, ou expira após 30 minutos independentemente do que foi definido em WriteCache.
Possível causa: 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 de WriteCache só se aplica no momento da escrita; leituras subsequentes sem uma expiração explícita encurtam silenciosamente o tempo de vida 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 o tempo de vida 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 de 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.
Possível causa: A folha de estilos 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 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 no XML de entrada.
Resolução:
- Atualize o XSLT para produzir saída XML: Altere a declaração de saída da folha de estilos para <xsl:output method="xml"/>, ou remova a declaração xsl:output inteiramente (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 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ó 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 SelectNodes.
Possível causa: Usar uma expressão XPath absoluta (uma 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: 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");
```

A saída de `HexToBinary` parece inalterada quando registrada

Sintoma: HexToBinary parece não ter efeito: o valor escrito no log de operação parece idêntico à entrada hexadecimal, sugerindo que a conversão não ocorreu.
Possível causa: WriteToOperationLog não consegue exibir dados binários brutos. Quando recebe um valor binário, converte-o 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` classifica 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.
Possível causa: SortArray realiza uma classificaçã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 classificação alfabética não corresponde a uma classificação baseada em data.
Resolução:
- Se você controlar a convenção de nomenclatura de arquivo, mude para um formato que seja classificado 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 de arquivo não puder ser alterado, analise a parte da data de cada nome de arquivo em uma chave classificável (por exemplo, YYYYMMDDHHMMSS) e classifique em relação à chave analisada em vez do nome de arquivo bruto.

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

Sintoma: Um valor passado através de URLEncode é enviado para o destino com alguns caracteres não codificados, causando a rejeição da solicitação ou má interpretação do valor pelo sistema receptor. Isso afeta comumente credenciais ou valores de consulta que contêm caracteres como $, + ou !.
Possíveis causas:
- URLEncode segue 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.
- O suporte a caracteres multibyte em URLEncode requer versão do agente 12.4 ou posterior. Em agentes anteriores, caracteres multibyte podem não ser codificados conforme 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 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 se 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 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
```
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 de Tomcat. Esse 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 conseguir evitar recursão profunda, use uma abordagem que não dependa dela.
- Observe que o limite de iteração de loop separado por script (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 falha de script

Sintoma: Um script de 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áveis globais feitas durante essa execução serão descartadas.
- Misturar 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 scripts JavaScript para que todas as atribuições de variáveis globais ocorram após lógica que possa falhar, ou use tratamento de erros para evitar falhas no meio do script.
- Para qualquer variável em um script JavaScript, use sintaxe $variable ou Jitterbit.SetVar/Jitterbit.GetVar, nunca ambas. Escolha uma e use-a consistentemente 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 destinam-se a variáveis do 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, portanto 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 do 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 prefixação com $ ou GetVar/SetVar, não ambas. Consulte também JavaScript: alterações de variável global perdidas na falha do 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 solução de problemas do API Manager para conhecer as causas completas e a resolução.

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 payload ou resposta hospedado e retorna um 507 mesmo quando há espaço em disco suficiente. 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 tem 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 conhecer a causa e a 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 é normalmente transitório e pode não ser reproduzível.
Resolução:
1. Tente novamente a operação.
2. Se o erro persistir, entre em contato com o suporte Jitterbit.

Erros em tempo de design

Esses problemas aparecem durante a construção, validação ou implantação de 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 {{icon.errorDiamondRed}} inválido na tela de design e no painel de projeto. Clique no ícone para visualizar a mensagem de erro específica.

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

Erro	Resolução
A operação está vazia.	A operação deve ter pelo menos uma etapa de operação.
A operação não está em conformidade com nenhum padrão válido. As regras e padrões de operação podem ser encontrados aqui.	A operação deve atender aos padrões de operação estabelecidos que o agente suporta e espera. Esses padrões são cobertos em Padrões de validação.
O esquema de transformação [origem / destino] não corresponde à estrutura de esquema fornecida pela atividade ["Activity Name"]. Abra a transformação ["Transformation Name"] na operação ["Operation Name"] e atualize o esquema de destino.	Em uma operação que contém uma transformação com um esquema fornecido pela atividade, o esquema fornecido pela atividade deve corresponder à estrutura de esquema fornecida por uma atividade adjacente.
A transformação ["Transformation Name"] tem um esquema de origem, mas nenhuma atividade de origem. Remova o esquema de origem da transformação ou adicione uma atividade de origem antes da transformação.	Se a operação contiver uma transformação com um esquema de origem fornecido pela atividade ou fornecido pela transformação, deve haver uma atividade de origem precedendo a transformação.
Atividades de destino HTTP que enviam sua resposta para uma segunda atividade de destino podem enviar respostas apenas para uma atividade de destino em todo o projeto. A atividade HTTP ["Target 1 Activity Name"] nesta operação está enviando sua resposta para várias atividades de destino em todo o projeto. Nesta operação, seu destino é ["Target 2A Activity Name"]. Na operação ["Operation 2"], seu destino é ["Target 2B Activity Name"]. Substitua a atividade ["Target 1 Activity Name"] por uma atividade duplicada em uma das operações. Você pode fazer isso encontrando a atividade ["Target 1 Activity Name"] na Aba de Componentes, abrindo o menu e duplicando. Arraste a atividade duplicada para a operação.	Em uma operação que usa o Padrão de arquivo de dois destinos e contém uma atividade de destino HTTP que escreve uma resposta para uma segunda atividade de destino, a atividade de destino HTTP também sendo usada em outra operação Padrão de arquivo de dois destinos deve escrever para a mesma atividade de destino. Nota: Esta regra de validação pode ser desabilitada, embora não seja recomendado. Para mais informações, consulte Erros de regra de validação HTTP abaixo.
"A operação ["Operation Name"] não pode ter mais de uma atividade de escuta ou baseada em evento: ["Activity Names"]."	Uma operação pode conter apenas uma atividade de escuta por operação.
"A operação ["Operation Name"] tem ["Activity Name"] como uma atividade de escuta ou baseada em evento -- essas atividades precisam ser a primeira na operação.	A operação deve atender aos padrões de operação estabelecidos para a atividade de escuta. Os padrões de operação que cada atividade de escuta pode ser usada com estão listados na documentação de cada atividade.
"A operação ["Operation Name"] não pode ter resultado ["On Success" / "On Fail" / "On SOAP Fault"] para a operação de destino ["Operation Name 2"] que tem uma atividade de escuta ou baseada em evento como primeira atividade."	Uma operação não pode usar ações de operação para invocar outra operação que contém uma atividade de escuta.
"A operação ["Operation Name"] começa com uma atividade de escuta ou baseada em evento ["Activity Name"] e não pode ter agendamento anexado."	Uma operação que contém uma atividade de escuta não pode ser executada em um agendamento.
"O script ["Script Name"] na operação ["Operation Name"] não pode usar RunOperation() para invocar a operação ["Operation Name 2"] que tem uma atividade de escuta ou baseada em evento.	Uma operação não pode usar a função `RunOperation` para invocar outra operação que contém uma atividade de escuta.

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 com dois destinos onde uma atividade HTTP na posição Destino 1 escreve uma resposta para 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 com dois destinos onde a atividade HTTP Destino 1 escreve para 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 seguinte exemplo:

Texto da caixa de diálogo

Erros de Validação

operationName
Atividades de destino HTTP que enviam sua resposta para uma segunda atividade de destino só podem enviar respostas para uma atividade de destino em todo o projeto. A atividade HTTP activityName nesta operação está enviando sua resposta para múltiplas atividades de destino em todo o projeto.

Nesta operação seu destino é targetName. Na operação otherOperation seu destino é otherTarget.

Substitua a atividade activityName por uma atividade duplicada em uma das operações. Você pode fazer isso encontrando a atividade activityName na Aba de Componentes, abrindo o menu e duplicando. Arraste a atividade duplicada para a operação.

Resolver erros de validação HTTP

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

Duplique a atividade de destino HTTP na posição Destino 1 de uma das operações que usa o padrão de arquivo HTTP com dois destinos.
Substitua a atividade de destino HTTP na posição Destino 1 das operações identificadas pela cópia duplicada.
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, você pode querer desabilitar essa regra de validação HTTP. Para desabilitar a regra, complete as seguintes etapas:

Abra as configurações do projeto:
Na aba Deploy, desabilite HTTP Validation Rule:
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 com dois destinos escreve para a atividade Destino 2 da última operação implantada. Esse comportamento pode causar a escrita de dados inválidos.

Cuidado

Desabilitar a regra de validação HTTP não é recomendado e pode resultar na escrita não intencional de dados inválidos para atividades de destino em operações que usam o padrão de arquivo com dois destinos.

Reabilitar a regra de validação HTTP

Se você desabilitou anteriormente a regra de validação HTTP e deseja reabilitá-la, complete as seguintes etapas:

Abra as configurações do projeto.
Na aba Deploy, habilite HTTP Validation Rule.
Clique em Save. Essa alteração é uma alteração em tempo de design e não implanta nenhuma alteração na nuvem Harmony.
Resolva erros de validação HTTP (consulte Resolver erros de validação HTTP).
Reimplante 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 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 exclusivos após importação de 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.
```
Possível causa: 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, mas uma importação de projeto completa não aplica essa verificação.
Resolução:
1. No painel de 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 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 sinaliza 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 ambiente de agente na nuvem

Sintoma: A importação ou migração de um projeto para um ambiente associado a um grupo de agente na 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 na nuvem não suportam esses conectores, portanto o Studio impede que o projeto seja importado ou migrado para um ambiente de agente na nuvem.
Resolução:
- Importe ou migre o projeto para um ambiente associado a um grupo de agente privado que tenha o conector necessário instalado.
- Se o projeto deve ser executado em agentes na nuvem, substitua as atividades de conector exclusivo 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 na 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 é em todo o projeto, não limitada à 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 ele for referenciado por mais de um componente, o Studio exibe um diálogo Schema usado por múltiplos componentes listando-os (consulte 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 que ele não sobrescreva o arquivo compartilhado.

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

Sintoma: Um projeto importado de um template de processo do Marketplace falha ao ser implantado 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 sua instância for diferente (por exemplo, se 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 remapeie-o a partir de um arquivo de amostra 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 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 workflow 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 workflow ativo de uma vez, portanto um workflow com um número muito grande de operações coloca altas demandas de memória no navegador.
Resolução:
- Divida workflows grandes em sub-workflows menores e vinculados. O Studio renderiza apenas a tela do workflow ativo, portanto menos operações por workflow melhora a responsividade. Use ações de operação para encadear sub-workflows.
- 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, o 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 Write do Variable.
  - Na segunda operação, leia de uma atividade Read do Variable 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 de 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 do Salesforce, que usam 2 threads por padrão.
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 novamente no 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 do que a taxa de transferência por operação, defina Max Number of Threads como 1. Cada chunk é processado sequencialmente, portanto, as atualizações de variáveis não são divididas entre threads.
- Se a taxa de transferência multi-thread for necessária, não acumule estado por registro em uma variável global ou de projeto. Em vez disso, coloque a saída de cada thread em um arquivo Temporary Storage exclusivo ou em uma tabela de banco de dados de staging, 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 forma mais 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 seja executada antes ou depois da transformação com chunking. Para detalhes sobre o comportamento de 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 aparecer 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 de 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, 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 de arquivos temporários (/tmp ou TemporaryFiles), e verifique se o host do agente possui espaço em disco livre adequado.
- Para grupos de agentes na nuvem, isso 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. Isso 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 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 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 da nuvem Harmony.
Possível causa: Quando o log de depuração de operação está 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 e não produtivos ou por um período de 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.

Operações agendadas não sendo executadas

Sintoma: Uma operação configurada com um agendamento de operação não é executada no horário agendado ou é despachada mas permanece em 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 entram em vigor 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á saturado de 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 execute operações agendadas no 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 na página Projects do Management Console, nas abas Operations e Schedules.
- Revise a configuração de agendamento, prestando atenção particular à configuração de fuso horário. Para 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 Management Console 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 Task Manager. No Linux e Docker, use o comando jitterbit status.
- Reimplante o projeto para forçar o agendamento a ser ressincronizado com o agente.
- Se operações estão presas em estado Pending, cancele-as pela página Runtime do Management Console e reinicie o serviço do agente.
- Se as falhas de agendamento se correlacionam com carga, reduza o número de operações de longa duração simultâneas. Em agentes privados, também revise o uso de CPU e memória e equilibre 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 é despachada mas depois trava 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 o 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 filha é executada em uma thread separada e a pai continua sem aguardar. 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 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 o comportamento equivalente em operações multi-thread em chunks, consulte Variable updates lost in chunked multi-threaded operations.
Resolução:
- Se a pai depende de 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ável global 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 tenha terminado; execute a operação de forma síncrona.

504 Gateway Timeout (operações acionadas por API)

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 subjacente está excedendo o timeout do gateway de API, ou a solicitação não pode ser atribuída a um agente disponível. Consulte HTTP 504 Gateway Timeout para as causas completas e resolução.

507 Armazenamento insuficiente

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 payload ou resposta hospedado e retorna um 507 mesmo quando há espaço em disco suficiente. 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 tem 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 conhecer a causa e a 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 é normalmente transitório e pode não ser reproduzível.
Resolução:
1. Tente novamente a operação.
2. Se o erro persistir, entre em contato com o suporte Jitterbit.

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 aparecer 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 de 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, 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 de arquivos temporários (/tmp ou TemporaryFiles), e verifique se o host do agente possui espaço em disco livre adequado.
- Para grupos de agentes na nuvem, isso 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. Isso 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 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.

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 da nuvem Harmony.
Possível causa: Quando o log de depuração de operação está 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 e não produtivos ou por um período de 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.

Falha de conexão com banco de dados do agente privado

Sintoma: Operações falham com:

Failed to connect to back-end database 'TranDb'

FATAL: query_wait_timeout

Possível causa: O banco de dados PostgreSQL interno do agente privado está indisponível ou o pool de conexões está esgotado.
Resolução: Consulte Falhas de conexão TranDb para obter as etapas completas de resolução.

Falha ao carregar certificado de cliente em agentes privados Linux

Sintoma: Uma operação que faz uma chamada de serviço web com TLS mútuo (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.
Possíveis causas:
- O usuário do sistema operacional que executa o agente Jitterbit não tem permissão de leitura para o arquivo de chave privada ou seus diretórios pai.
- Um módulo de segurança Linux como SELinux ou AppArmor está bloqueando o acesso do agente ao arquivo de chave privada.
Resolução:
- Certifique-se de que a conta que executa o agente Jitterbit tem acesso de leitura ao arquivo de chave privada e a todos os diretórios pai.
- Verifique se SELinux ou AppArmor está restringindo o acesso ao arquivo de chave e ajuste a política ou o contexto do arquivo conforme necessário.

Erros de validação de operação

As operações devem ser válidas antes de serem implantadas. Para obter a lista completa de mensagens de erro de validação e suas resoluções, consulte Erros de validação de operação no guia de solução de problemas de Operação.

Nomes de componentes devem ser exclusivos após importação de 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.
```
Possível causa: 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, mas uma importação de projeto completa não aplica essa verificação.
Resolução:
1. No painel de 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 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 sinaliza conflitos com componentes de mesmo nome já no projeto de destino e permite substituí-los ou manter ambos.

Bloco de conector somente para agente privado impede importação para ambiente de agente na nuvem

Sintoma: A importação ou migração de um projeto para um ambiente associado a um grupo de agente na 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 na nuvem não suportam esses conectores, portanto o Studio impede que o projeto seja importado ou migrado para um ambiente de agente na nuvem.
Resolução:
- Importe ou migre o projeto para um ambiente associado a um grupo de agente privado que tenha o conector necessário instalado.
- Se o projeto deve ser executado em agentes na nuvem, substitua as atividades de conector exclusivo 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 na nuvem) antes de importar.

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 fazem referência a dois ou mais nós de loop de origem diferentes. Cada nó de loop de destino pode iterar sobre apenas 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 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.

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

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

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 de 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 direcionar apenas a seção CDATA, toda a string XML que a contém pode ser substituída.

O exemplo a seguir é considerado inválido sem essas substituições:
```
{
  "name": "Jitterbit",
  "data": "<xml><content><![CDATA[<greeting>Hello, world!</greeting>]]></content></xml>"
}
```

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 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), portanto, 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 downstream (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, portanto, atualize o agente primeiro se estiver em uma versão anterior.

Caracteres especiais em esquemas JSON fornecidos por conectores

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 sublinhados (_). Ao usar processamento JSON legado (o padrão para projetos criados antes do Harmony release 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 fornece 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 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 log de depuração ativado:

Caracteres multibyte corrompidos em uma resposta grande do conector

Sintoma: Um caractere multibyte em uma resposta do conector JSON está corrompido. O texto corrompido mostra 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 antes na resposta não é afetado.
Possível causa: Nas versões do agente 12.8 e 12.9, 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 do agente 12.10 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. Usar um resulta em um erro de runtime:
```
Failed to initialize transformation "<transformation name>". Failed to expand the (source|target) tree for the path: <path to substitution head node>.
```
Esse erro também pode ocorrer por outros motivos, 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 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.).

Importação de 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 runtime 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 quando executada.

Possível causa: Importar um arquivo de mapeamento que adicionou nós duplicados ao esquema de destino não aplicou a alteração correspondente à definição de 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.
Resoluçã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. Reimportar ressincroniza a definição de 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.

Aviso de subelemento extra nos logs de operação

Sintoma: Uma mensagem extra subelement 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 de resposta.
Resolução: Se for necessário capturar os dados adicionais, atualize o esquema para incluir os campos extras.

Limite de iteração 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 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çõ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.

`RunOperation` para de executar após 50 chamadas síncronas em um loop `While`

Sintoma: Após atualizar um agente 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 de retorno da função ou chame GetLastError. O log da operação mostra uma entrada identificando a operação sendo invocada quando o limite foi atingido.
Possível causa: A partir da versão 12.11 do agente, um limite no nível do agente (MaxSynchronousRunOperationCallsInLoop na seção [OperationEngine] do arquivo jitterbit.conf, 50 por padrão) limita o número de chamadas síncronas RunOperation, RunOperationFromProject e ReRunOperation feitas dentro de um único loop While; todos os três compartilham uma contagem cumulativa por loop. Quando o limite é atingido, cada chamada subsequente retorna false sem gerar um erro, portanto um loop que não verifica o valor de retorno continua iterando sem perceber que as chamadas posteriores não fizeram nada.
Resolução:
- Se o loop não verificar o valor de retorno, encapsule a chamada para que um limite acionado 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 da execução do loop, desde que as substituições por operação sejam permitidas (MaxSynchronousRunOperationCallsInLoopOverrideAllowed).
- Para aumentar o padrão em toda a plataforma, aumente MaxSynchronousRunOperationCallsInLoop na seção [OperationEngine] do arquivo jitterbit.conf.

Comparar uma string com um número produz 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 a ramificação errada é executada:
```
$value = "test";
If($value == 0, WriteToOperationLog("equal"), WriteToOperationLog("not equal"));
// logs "equal", even though "test" is not 0
```
Causa: Quando os dois operandos são de 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 em relação a 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 puder chegar como qualquer tipo, converta ambos os operandos para o mesmo tipo (por exemplo, com String) antes de comparar.

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

Sintoma: Devido a alterações 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 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 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 retém o prefixo de namespace original, portanto o esquema é idêntico a 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.

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 converte 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. Em contraste, um valor como "1string" produziria 1, já que o dígito inicial é mantido.
Resolução:
1. Verifique a definição de esquema do 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 origem simples

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 fonte simples. Não ocorre com esquemas espelhados ou esquemas JSON.
Possível causa: O modo de transformação de 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 desabilita transformações de streaming definindo 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.

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

Sintoma: Uma operação é concluída com 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.
Possível causa: 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 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 uma 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.
Possível causa: ReadFile não é confiável com conteúdo de arquivo binário e geralmente 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 conteúdo de arquivo bruto lido com ReadFile (por exemplo, um arquivo EDI bruto) para um campo de destino XML ou JSON em 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: Corresponda 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 escrever 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 escrita para remover o arquivo existente.
- Alternativamente, use um nome de arquivo dinâmico que inclua um timestamp ou identificador único para evitar conflitos.

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

Sintoma: Um script usando DeleteFiles falha com um erro quando o caminho de origem ou diretório 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 falhar na 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 causar a interrupção de todo o script.
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 o payload JSON imediatamente antes da chamada GetJSONString para verificar a estrutura real e confirmar o caminho.

`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 de agente anteriores à 12.9, essa combinação não desmapeava o campo.
- Unmap é chamado de dentro do script invocado por RunScript, em vez de diretamente na própria expressão de mapeamento do campo de destino. RunScript retorna o resultado do script chamado como uma string em vez de propagar um sinal de desmapeamento de volta 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 forem ambos chamados diretamente na expressão de mapeamento do campo de destino, atualize para a versão 12.9 do agente ou posterior.
- Se Unmap for chamado de dentro do script invocado por RunScript, mova a chamada Unmap para fora do script chamado e para a própria expressão de mapeamento do campo de destino, por exemplo:
```
RunScript("<TAG>script:MyScript</TAG>"); If(<condition>, Unmap(), <value>);
```

`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 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 de transação explícito e 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 indefinida 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 é suportado apenas por 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, mude o endpoint de banco de dados para usar um driver JDBC em vez de ODBC.
- Se não for possível trocar drivers, 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 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 faz distinção 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 é suportado 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, mude 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 anterior à chamada AESDecryption para habilitar compatibilidade com OpenSSL 3.
- Alternativamente, substitua AESDecryption por AESDecryptionEx, que suporta OpenSSL 3 por padrão em versões de agente 11.42 ou posterior.

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

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 do Salesforce, que usam 2 threads por padrão.
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 novamente no 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 do que a taxa de transferência por operação, defina Max Number of Threads como 1. Cada chunk é processado sequencialmente, portanto, as atualizações de variáveis não são divididas entre threads.
- Se a taxa de transferência multi-thread for necessária, não acumule estado por registro em uma variável global ou de projeto. Em vez disso, coloque a saída de cada thread em um arquivo Temporary Storage exclusivo ou em uma tabela de banco de dados de staging, 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 forma mais 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 seja executada antes ou depois da transformação com chunking. Para detalhes sobre o comportamento de chunking com variáveis, consulte Use variables with chunking.

Transformação descarta 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) descarta 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 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 é 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 à esquerda e à direita dos valores de campo CSV por padrão. Registros que diferem apenas por espaços à esquerda ou à direita se tornam idênticos após a remoção 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 contorna 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 definindo uma variável Jitterbit em uma etapa de script anterior à transformação. Para transformações simples para simples, defina jitterbit.transformation.disable_normalization como true. Para transformações simples 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 com cuidado.
- Se os duplicados forem causados especificamente por diferenças de espaço em branco, defina jitterbit.source.preserve_char_whitespace como true em uma etapa de script anterior à transformação. Isso preserva o espaço em branco durante a análise para que os registros afetados permaneçam distintos.

IDs numéricos longos são corrompidos na saída de 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 e produzindo um valor incorreto no destino.
Possível causa: O campo de origem ou destino é implicitamente tipado 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 tipado numericamente, converta o valor explicitamente com String antes de mapeá-lo:
```
String($source.numericId)
```

Saída de transformação JSON omite campos `null` e strings vazias

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 a jusante 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 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 uma etapa de script usando concatenação de strings e envie-o através de um conector HTTP v2 com um corpo de solicitação sem schema.

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 uma etapa de script anterior à transformação, defina $jitterbit.target.xml.include_null_xml = false para remover completamente da saída os nós com um valor nulo ou vazio. Se, em vez disso, 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 nulos 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 (BOM) UTF-8, 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, você também pode definir explicitamente a codificação de caracteres como UTF-8 antes da atividade de origem ser executada, por exemplo $jitterbit.source.text.character_encoding = "utf-8";. A versão do agente 12.7 e posterior usam UTF-8 por padrão.

Variáveis de 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 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).
Possível causa: 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, 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 de projeto: Na configuração da variável de projeto, insira o valor a ser usado durante o teste 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), portanto em tempo de execução também atua como um fallback quando a variável não está definida. Consulte 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 script em si, antes da linha que a usa. Como uma variável global obtém seu valor da execução do script em vez da 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 é derivado em um script ou quando você não deseja 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 abrange tanto o método de pill de variável quanto o método de sintaxe inline para campos que não mostram um pill).

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, Cadeia de Conexão ou um endereço de servidor) definido como uma variável global ou de projeto. Testar um script executa apenas o script testado, portanto a variável ainda não recebeu seu valor em tempo de execução quando a função resolve a conexão. 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 de projeto retornam valores vazios durante testes de script e transformaçã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 aparenta não ter valor. A lógica downstream que depende da verificação de nulo se comporta de forma inesperada ou produz resultados incorretos.
Possível causa: JSON distingue entre um valor ausente ou explicitamente null e uma string vazia (""). Um campo definido como "" em JSON é uma string vazia, não nulo, portanto IsNull corretamente retorna false 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 true para strings vazias dependiam de um comportamento anterior que não é mais correto.
Resolução:
- Use IfEmpty para lidar com 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 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 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 com o número `0` retorna inesperadamente `true`

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 outra lógica que verifica zero produzem resultados inesperados.
Possível causa: Quando o Jitterbit Script compara valores de tipos de dados diferentes, tenta converter ambos os operandos para 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, 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 inesperados de ponto flutuante

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 é avaliado como 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, portanto a aritmética nelas pode acumular pequenos erros de arredondamento. A subtração que cancela a maior parte 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 computado.
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); // returns 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);
```

Funções de data retornam meia-noite em vez de um valor somente 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 somente de data (2026-01-01), o que pode quebrar a lógica downstream que espera o formato mais curto. CVTDate não é afetado.
Possível causa: Com a versão 12.8 do agente 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 somente de data, enquanto qualquer outra hora era preservada corretamente.
Resolução: Se a lógica downstream exigir um valor somente 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 que o esperado

Sintoma: Um valor escrito no cache com uma expiração longa (por exemplo, 24 horas) desaparece bem antes desse tempo passar, ou expira após 30 minutos independentemente do que foi definido em WriteCache.
Possível causa: 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 de WriteCache só se aplica no momento da escrita; leituras subsequentes sem uma expiração explícita encurtam silenciosamente o tempo de vida 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 o tempo de vida 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 de 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.
Possível causa: A folha de estilos 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 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 no XML de entrada.
Resolução:
- Atualize o XSLT para produzir saída XML: Altere a declaração de saída da folha de estilos para <xsl:output method="xml"/>, ou remova a declaração xsl:output inteiramente (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 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ó 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 SelectNodes.
Possível causa: Usar uma expressão XPath absoluta (uma 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: 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");
```

Saída de `HexToBinary` aparece inalterada quando registrada

Sintoma: HexToBinary parece não ter efeito: o valor escrito no log de operação parece idêntico à entrada hexadecimal, sugerindo que a conversão não ocorreu.
Possível causa: WriteToOperationLog não consegue exibir dados binários brutos. Quando recebe um valor binário, converte-o 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` classifica 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.
Possível causa: SortArray realiza uma classificaçã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 classificação alfabética não corresponde a uma classificação baseada em data.
Resolução:
- Se você controlar a convenção de nomenclatura de arquivo, mude para um formato que seja classificado 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 de arquivo não puder ser alterado, analise a parte da data de cada nome de arquivo em uma chave classificável (por exemplo, YYYYMMDDHHMMSS) e classifique em relação à chave analisada em vez do nome de arquivo bruto.

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

Sintoma: Um valor passado através de URLEncode é enviado para o destino com alguns caracteres não codificados, causando a rejeição da solicitação ou má interpretação do valor pelo sistema receptor. Isso afeta comumente credenciais ou valores de consulta que contêm caracteres como $, + ou !.
Possíveis causas:
- URLEncode segue 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.
- O suporte a caracteres multibyte em URLEncode requer versão do agente 12.4 ou posterior. Em agentes anteriores, caracteres multibyte podem não ser codificados conforme 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 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 se 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 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
```
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 de Tomcat. Esse 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 conseguir evitar recursão profunda, use uma abordagem que não dependa dela.
- Observe que o limite de iteração de loop separado por script (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 de script

Sintoma: Um script de 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áveis globais feitas durante essa execução serão descartadas.
- Misturar 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 scripts JavaScript para que todas as atribuições de variáveis globais ocorram após lógica que possa falhar, ou use tratamento de erros para evitar falhas no meio do script.
- Para qualquer variável em um script JavaScript, use sintaxe $variable ou Jitterbit.SetVar/Jitterbit.GetVar, nunca ambas. Escolha uma e use-a consistentemente 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 destinam-se a variáveis do 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, portanto 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 do 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 prefixação com $ ou GetVar/SetVar, não ambas. Consulte também JavaScript: alterações de variável global perdidas na falha do 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
```

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 é em todo o projeto, não limitada à 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 ele for referenciado por mais de um componente, o Studio exibe um diálogo Schema usado por múltiplos componentes listando-os (consulte 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 que ele não sobrescreva o arquivo compartilhado.

A implantação do modelo de processo do Marketplace falha devido a incompatibilidade de schema

Sintoma: Um projeto importado de um template de processo do Marketplace falha ao ser implantado 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 sua instância for diferente (por exemplo, se 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 remapeie-o a partir de um arquivo de amostra 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 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 workflow 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 workflow ativo de uma vez, portanto um workflow com um número muito grande de operações coloca altas demandas de memória no navegador.
Resolução:
- Divida workflows grandes em sub-workflows menores e vinculados. O Studio renderiza apenas a tela do workflow ativo, portanto menos operações por workflow melhora a responsividade. Use ações de operação para encadear sub-workflows.
- Se a lentidão ocorrer especificamente ao salvar um script grande, divida o script em scripts menores e chame-os usando RunScript.

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

Sintoma: Uma atividade do Amazon Bedrock falha com:

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

Possível causa: Alguns modelos, incluindo os modelos GPT-5.6 da OpenAI, não suportam throughput sob demanda e requerem o ID de um perfil de inferência entre regiões em vez do ID do modelo retornado na lista Selecionar um modelo da atividade.
Resolução:
1. No AWS Management Console, acesse Amazon Bedrock > Perfis de inferência e localize o ID do perfil de inferência para o modelo. Por exemplo, o ID do perfil de inferência para anthropic.claude-3-5-haiku-20241022-v1:0 nos EUA é us.anthropic.claude-3-5-haiku-20241022-v1:0. Para os modelos GPT-5.6 da OpenAI, os prefixos de ID de perfil de inferência válidos variam por modelo e região (por exemplo, us. ou global.), como us.openai.gpt-5.6-terra ou global.openai.gpt-5.6-terra. Para o ID exato do perfil de inferência para seu modelo e região, consulte os cartões de modelo da AWS para GPT-5.6 Sol, GPT-5.6 Terra e GPT-5.6 Luna.
2. Digite o ID do perfil de inferência usando a opção Inserir identificador de modelo na configuração da atividade.

Cloud Datastore: a atividade Delete Items relata sucesso mas não deleta o registro

Sintoma: Uma atividade Delete Items do Cloud Datastore relata sucesso no log de operações, mas o registro de destino ainda existe quando consultado posteriormente.
Possível causa: Delete Items identifica registros pela Chave (ou Chave Alternativa) do armazenamento, fornecida no array keys ou ids da solicitação. (Ambos os arrays aceitam valores de chave ou chave alternativa.) Se o ID interno do registro for fornecido em vez do valor da chave, nenhum item corresponderá, e a atividade relatará sucesso sem deletar nada.
Resolução:
- Na transformação que prepara a solicitação Delete Items, mapeie a Chave (ou Chave Alternativa) do armazenamento, não o ID interno do registro.
- Ao encadear a partir de uma atividade Query Items, mapeie o valor key da resposta da consulta para a solicitação de exclusão.

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

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

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

Sintoma: Uma função DBLookup ou DBExecute direcionada a um banco de dados PostgreSQL ou SQL Server por um driver JDBC falha em tempo de execução com:
```
Base64 decoding failed. Reason: error:00000000:lib(0)::reason(0)
```
Isso ocorre sempre que o valor retornado se assemelha a dados codificados em Base64, como um JWT ou outro token de acesso, mesmo que a mesma consulta seja bem-sucedida quando executada diretamente no banco de dados.
Possível causa: Versões do agente anteriores à 12.9 podem tentar incorretamente decodificar em Base64 um valor de resultado JDBC que corresponda a um padrão semelhante a Base64, independentemente de o valor ser dados realmente codificados em Base64.
Resolução:
- Para agentes privados, atualize para a versão 12.9 ou posterior. Agentes em nuvem recebem a atualização automaticamente.
- Se não conseguir atualizar imediatamente, evite disparar a verificação de Base64 convertendo o valor afetado para hexadecimal na consulta SQL e depois decodificando-o em uma etapa de script usando HexToString. Por exemplo, no PostgreSQL: SELECT encode(<column>, 'hex'). Use o equivalente SQL decode(...,'hex') com StringToHex ao escrever o valor de volta no banco de dados.

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

Sintoma: Ao ler ou escrever em um banco de dados através do conector de Banco de dados usando um driver ODBC, caracteres multibyte ou não-ASCII (por exemplo, caracteres acentuados ou não-latinos) não são tratados corretamente.
Possível causa: O suporte a caracteres multibyte para o conector de Banco de dados sobre um driver ODBC não está habilitado por padrão. A variável Jitterbit jitterbit.scripting.db.multibyte.enable deve ser definida como true. Este suporte está disponível na versão 12.6 do agente e posterior, e não é necessário ao usar um driver JDBC.
Resolução:
1. Confirme que o agente é versão 12.6 ou posterior.
2. Defina a variável jitterbit.scripting.db.multibyte.enable como true antes da operação de banco de dados ser executada. Por exemplo, em uma etapa de script:
```
$jitterbit.scripting.db.multibyte.enable = true;
```
Alternativamente, use um driver JDBC para a conexão de banco de dados, que trata caracteres multibyte sem esta variável.

Database: conexão bloqueada por política de segurança

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

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

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

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

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

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

Possível causa: A versão 12.10 do agente e posterior restringe certas conexões de banco de dados e parâmetros de string de conexão por padrão, por segurança. Isso inclui conexões para localhost ou 127.0.0.1, e parâmetros de string de conexão específicos para os drivers MySQL, PostgreSQL, Oracle e SQL Server. Uma conexão que funcionava antes pode falhar após atualizar um agente privado para a versão 12.10, porque a restrição se aplica por padrão mesmo que a seção [JdbcSecurity] não seja adicionada automaticamente a um arquivo jitterbit.conf existente.
Resolução: Em um agente privado, configure a seção [JdbcSecurity] do arquivo de configuração do agente (jitterbit.conf) para permitir a conexão ou parâmetro específico que você precisa, depois reinicie o agente.

Database: timeouts de conexão sob carga

Sintoma: Operações de origem ou destino de banco de dados falham intermitentemente sob carga concorrente pesada, com uma exceção similar a:
```
java.sql.SQLException: Network error IOException: Connection timed out
Caused by: java.net.ConnectException: Connection timed out
```
Possível causa: Cada operação de banco de dados abre uma nova conexão JDBC física e a fecha depois, em vez de reutilizar uma existente. Sob carga concorrente, isso cria rotatividade de conexão suficiente contra o banco de dados de destino para que algumas tentativas de conexão expirem.
Resolução: A versão 12.11 do agente e posterior pode agrupar e reutilizar conexões em vez de abrir e fechar uma para cada operação, reduzindo essa rotatividade. Em um agente privado, defina jdbc.hikari.enabled=true na seção [SourceTargetPooling] do arquivo de configuração do agente (jitterbit.conf), depois reinicie o agente.

Database: erros de comprimento de campo em Insert, Update ou Upsert

Sintoma: Uma atividade Banco de dados Insert, Update ou Upsert falha com status de operação Erro quando um valor de origem mapeado é mais longo do que o permitido pela coluna de destino. O log de operação contém um dos seguintes:
```
One or more values were truncated when inserting and/or updating the field
```
```
Field value too long
FieldName: m_site  Length: 3  Length Allowed: 1
```
Possível causa: Por padrão, se um valor de origem mapeado exceder o comprimento definido da coluna de destino, a atividade rejeita a linha e relata um status Erro em vez de truncar o valor.
Resolução:
1. Na configuração da atividade Insert, Update ou Upsert do Banco de dados, ative Permitir truncamento de campos de caracteres para evitar erros de comprimento de campo. Com essa opção ativada, valores que excedem o comprimento do campo de destino são truncados e a operação relata um status Sucesso com Informações em vez de Erro.
2. Se o truncamento não for aceitável, corte ou transforme o campo de origem no mapeamento de transformação para que os valores nunca excedam o comprimento da coluna de destino, ou amplie a coluna de destino no lado do banco de dados.
3. Reimplante e execute novamente a operação.

Database: JAR do driver JDBC sobrescrito em atualizações de agente

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

Database: caracteres especiais em nomes de coluna causam falhas de consulta

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

Database: instrução SQL excede limite de 2.000 caracteres

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

IBM DB2 on iSeries: falha na conexão JDBC

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

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

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

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

Sintoma: Uma conexão de Banco de Dados usando autenticação Kerberos falha com:
```
Could not initialize class com.microsoft.sqlserver.jdbc.KerbAuthentication
```
Possível causa: Os arquivos de configuração do Kerberos no host do agente não têm as permissões de arquivo corretas.
Resolução:
1. No host do agente privado, defina as permissões de arquivo nos arquivos de configuração do Kerberos (jaas.conf, krb5.conf e o arquivo de cache de ticket do Kerberos) como 644:
```
chmod 644 jaas.conf krb5.conf krb5cc_agent
```
2. Reinicie o agente após aplicar as alterações de permissão.

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

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

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

Sintoma: Uma atividade de Inserção ou Atualização de Banco de Dados direcionada a um arquivo Microsoft Excel (via ODBC) falha com:
```
[Microsoft][ODBC Excel Driver] A operação deve usar uma consulta atualizável
```
Possível causa: O driver ODBC do Excel abre o arquivo do Excel em modo somente leitura por padrão, a menos que a string de conexão defina explicitamente o modo leitura/escrita.
Resolução: No campo Connection String da conexão de banco de dados (inserido em Optional Settings com Use Connection String selecionado), adicione ReadOnly=0; ao final da string de conexão para abrir o arquivo do Excel em modo leitura/escrita.

MySQL: acesso negado apesar de credenciais corretas

Sintoma: A conexão com um banco de dados MySQL usando o conector de banco de dados falha com:
```
Access denied for user 'root'@'%' to database 'test'
```
mesmo quando o nome de usuário e a senha estão corretos.
Possível causa: O MySQL pode conceder permissões diferentes com base no endereço IP do cliente. Uma conta de usuário pode ter os privilégios necessários de endereços IP específicos, mas não do endereço IP do agente privado.
Resolução:
- No MySQL, verifique se a conta de usuário tem as concessões necessárias para conexões do endereço IP do agente privado. A sintaxe exata de concessão varia de acordo com a versão do MySQL (consulte a documentação do MySQL ou entre em contato com o administrador do MySQL), mas geralmente tem a forma:
```
GRANT ALL ON database.* TO 'user'@'agent-ip';
```
- Teste a conectividade usando um cliente MySQL instalado diretamente no host do agente para determinar se o problema é baseado em rede ou específico do Jitterbit.

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

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

MySQL: Driver ODBC não aparece na lista suspensa do Studio

Sintoma: Ao configurar uma conexão de banco de dados com MySQL usando um driver ODBC em um agente privado, o driver instalado não aparece no menu suspenso Driver no Studio.
Possível causa: O gerenciador ODBC no host do agente privado não está mostrando o driver, geralmente devido a uma incompatibilidade entre 32 bits e 64 bits ou uma instalação incompleta do driver.
Resolução:
- No host do agente privado (Windows), abra Data Sources (ODBC) (em Administrative Tools) e confirme se o driver ODBC do MySQL está listado. Para opções de driver MySQL, consulte Conectar ao MySQL.
- Confirme se o agente está se conectando à máquina correta: o driver ODBC deve estar instalado no host do agente, não na máquina do usuário do Studio.

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

Sintoma: Um teste de conexão do conector de banco de dados com PostgreSQL falha com um erro de "incompatibilidade de codificação do cliente".
Possível causa: A codificação que o servidor PostgreSQL usa difere da codificação padrão assumida pelo driver ODBC do PostgreSQL.
Resolução:
- Nas configurações de conexão do banco de dados, adicione ConnSettings=SET CLIENT_ENCODING to 'LATIN1' (substituindo a codificação real do servidor) ao campo Additional Connection String Parameters.
- No Windows, se o servidor usar uma codificação Cirílica como WIN1251, defina também a codificação do cliente como WIN1251 nas configurações do driver ODBC.

PostgreSQL: Use o driver fornecido pela Jitterbit no Linux

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

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

Sintoma: Para agentes privados, uma conexão de Banco de Dados com SQL Server usando um driver JDBC e autenticação integrada do Windows falha com:
```
This driver is not configured for integrated authentication. ClientConnectionId:...
```
Os logs do agente também podem exibir:
```
java.lang.UnsatisfiedLinkError: no mssql-jdbc_auth-8.2.0.x64 in java.library.path
```
Possíveis causas:
- A DLL mssql-jdbc_auth necessária para autenticação integrada do Windows está ausente dos diretórios JRE que o agente Jitterbit usa em tempo de execução. Colocar a DLL no mesmo diretório que o arquivo JDBC JAR não é suficiente.
- A string de conexão não inclui o parâmetro integratedSecurity=true.
Resolução:
1. No host do agente privado, copie mssql-jdbc_auth-x.x.x.x64.dll (da distribuição do driver JDBC, usando a versão que corresponde ao arquivo JDBC JAR incluído no seu agente) para <JITTERBIT_HOME>/jre/bin e <JITTERBIT_HOME>/jre/lib. Faça backup do arquivo, pois ele pode ser removido durante atualizações principais do agente.
2. Nas configurações de conexão do Banco de Dados, adicione integratedSecurity=true ao campo Parâmetros Adicionais da String de Conexão.
3. Reinicie o serviço do agente Jitterbit.

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

Sintoma: Uma conexão de Banco de Dados usando autenticação do Windows do SQL Server falha mesmo quando as credenciais de domínio parecem estar corretas.
Possível causa: O usuário de domínio do Windows que executa o serviço do agente Jitterbit não possui os privilégios de nível do SO necessários para a Segurança Integrada do Windows.
Resolução:
1. Conceda ao usuário de domínio os privilégios do Windows Fazer logon como um serviço e Agir como parte do sistema operacional no host do agente privado.
2. Confirme que o usuário de domínio tem permissões de leitura e escrita no diretório de instalação do agente Jitterbit.
3. Reinicie o serviço do agente Jitterbit após aplicar as alterações de privilégios.

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

Sintoma: Uma operação do conector de Banco de Dados que escreve em uma tabela do SQL Server com uma coluna de identidade falha com:
```
Database Error: Cannot insert explicit value for identity column in table '<table>' when IDENTITY_INSERT is set to OFF.
```
Possível causa: A coluna de identidade está incluída na instrução INSERT que o conector de Banco de Dados gera para o destino. O SQL Server rejeita um INSERT que faz referência a uma coluna de identidade em sua lista de colunas (com um valor explícito ou nulo) enquanto IDENTITY_INSERT está definido como OFF. Mapear o campo para um valor nulo não o exclui: um campo de destino é omitido do INSERT apenas quando é mapeado com a função Unmap.
Resolução:
- Para permitir que o SQL Server atribua o valor de identidade automaticamente, exclua a coluna do INSERT mapeando o campo de destino de identidade com a função Unmap. Para excluir a coluna apenas quando a origem não fornece um valor, use um mapeamento condicional:
```
If($source.id != "", $source.id, Unmap())
```
  Quando a condição é falsa, Unmap remove a coluna do INSERT e o SQL Server atribui o próximo valor de identidade. (Fornecer um valor explícito na ramificação verdadeira ainda requer que IDENTITY_INSERT esteja ON; veja a próxima opção.)
- Se for necessário inserir valores explícitos na coluna de identidade, defina IDENTITY_INSERT na tabela de destino em scripts pré e pós-SQL dentro da atividade:
```
SET IDENTITY_INSERT <table> ON;
```
```
SET IDENTITY_INSERT <table> OFF;
```
  Use esta opção apenas quando quiser controlar intencionalmente os valores de identidade de fora do banco de dados. Ela permite que valores explícitos sejam inseridos na coluna de identidade.

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

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

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

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

Possível causa: As versões atuais do driver SQL Server MS JDBC solicitam uma conexão criptografada por padrão e validam o certificado que o servidor de banco de dados apresenta. A conexão falha quando esse certificado não pode ser rastreado até uma autoridade de certificação (CA) que o agente já confia, como um certificado autoassinado, um certificado emitido internamente ou o certificado da CA do Amazon RDS que uma instância do Amazon RDS para SQL Server apresenta. Trata-se de uma falha de confiança de certificado e não de criptografia, portanto um banco de dados pode ter criptografia ativada e um certificado válido instalado e ainda assim falhar. A versão 12.8 do agente atualizou o driver agrupado para uma versão que solicita criptografia por padrão, portanto uma conexão configurada antes dessa atualização pode falhar depois.
Resolução: Digite encrypt=false; no campo Parâmetros de Cadeia de Conexão Adicionais em Configurações Opcionais da conexão de Banco de Dados, ou inclua-o em uma cadeia de conexão manual. Isso funciona em agentes na nuvem e privados. Para mais informações, consulte Criptografia de conexão e certificados de servidor.

Aviso

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

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

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

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

Sintoma: Um teste de conexão com uma conta do Gmail usando Autenticação Básica falha com um erro de autenticação, mesmo quando a senha correta da conta do Google é inserida.
Possível causa: O Google requer uma senha de app para contas com Verificação em 2 Etapas ativada. A senha da conta do Google não é aceita por SMTP ou IMAP quando a Verificação em 2 Etapas está ativa; apenas senhas de app são aceitas.
Resolução:
1. Na sua conta do Google, gere uma senha de app para a aplicação Jitterbit (consulte a página Fazer login com senhas de app do Google).
2. Na configuração da conexão de Email no Studio, insira a senha de app no campo Senha SMTP e/ou Senha IMAP em vez da senha da conta do Google.

Email: Falha na assinatura S/MIME ou rejeição por provedores de email em nuvem

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

Email: Falha na autenticação do Microsoft 365 (ROPC) quando MFA está ativado

Sintoma: Uma conexão OAuth 2.0 do Microsoft 365 que usa a concessão Resource Owner Password Credentials (ROPC) falha na autenticação, mesmo quando o nome de usuário, senha, ID do cliente, ID do locatário e segredo do cliente estão todos corretos.
Possível causa: A autenticação ROPC requer que a autenticação multifator (MFA) seja desativada para as credenciais do Microsoft 365 usadas com o conector. A concessão ROPC não consegue satisfazer um desafio de MFA, portanto, a solicitação de token falha quando uma política de MFA se aplica à conta.
Resolução:
- Use uma conta do Microsoft 365 cujas credenciais não estejam sujeitas a uma política de MFA. Para manter a segurança, crie um locatário ou diretório dedicado do Microsoft Entra ID que não imponha MFA, conforme descrito em Pré-requisitos para Microsoft 365.
- Se não for possível remover MFA da conta, use um método de autenticação diferente e suportado para a conexão em vez de ROPC.

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

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

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

Sintoma: Uma atividade de leitura do FTP, Compartilhamento de Arquivo ou Armazenamento Local falha porque o arquivo que ela espera ler não está mais no caminho de origem:
```
Failed to read file from the source "Read". Reason: No files match the file filter "<filter>".
```
A atividade que processou anteriormente o arquivo foi bem-sucedida; a falha ocorre em uma etapa posterior (geralmente uma etapa de arquivo ou notificação) que tenta ler o mesmo arquivo com o mesmo filtro.
Possíveis causas:
- A atividade de processamento já moveu ou deletou o arquivo de origem como parte de seu comportamento Após Processamento, então a etapa de arquivo não tem nada para corresponder.
- Uma operação filha é iniciada de forma assíncrona e a operação pai tenta ler o arquivo de saída da filha antes de ela terminar de escrevê-lo.
- Uma atividade Escrever do FTP com Usar Renomeação FTP habilitada (o padrão) escreve o arquivo com um nome temporário e o renomeia para o nome final ao concluir. Uma operação de leitura posterior que é executada antes da renomeação ser concluída não encontrará o arquivo.
Resolução:
- Confirme se a etapa anterior já tratou o arquivamento através de suas opções Após Processamento integradas (mover, renomear, deletar). Se sim, uma etapa de arquivo separada é redundante e deve ser removida.
- Se uma etapa de arquivo separada for necessária, redesenhe a cadeia para que o processamento e o arquivamento ocorram contra a mesma referência de arquivo em memória, em vez de reler da origem. Por exemplo, passe o conteúdo lido através do Armazenamento Temporário para a etapa de arquivo, em vez de reler o caminho de origem.
- Se uma etapa posterior ler a saída produzida por uma operação filha, execute a filha de forma síncrona para que sua saída exista antes da leitura. Defina o Tipo de execução da ferramenta Invocar Operação como Sincronamente, ou, ao chamar a operação a partir de um script, execute RunOperation de forma síncrona (o padrão). Inserir um atraso fixo (por exemplo, com a função Sleep) adiciona latência e não garante que o arquivo esteja pronto.
- Se uma atividade Escrever do FTP estiver escrevendo no mesmo local, verifique se Usar Renomeação FTP está habilitada na atividade FTP Write. Se a leitura posterior for executada antes da renomeação ser concluída, desabilite Usar Renomeação FTP na atividade de escrita, ou garanta que a operação de leitura não seja executada até que a operação de escrita seja totalmente concluída.

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

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

FTP, Compartilhamento de Arquivo e Armazenamento Local: Palavras-chave de nome de arquivo não resolvidas em caminhos de pasta de sucesso e erro

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

FTP, Compartilhamento de Arquivo, Armazenamento Local e Armazenamento Temporário: Gravar Cabeçalhos não produz um arquivo apenas com cabeçalho quando a origem não retorna registros

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

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

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

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

Sintoma: Uma operação SFTP usando autenticação de chave privada SSH falha com Login denied. Authentication failure., mesmo que as mesmas chaves se autentiquem com sucesso a partir de um cliente SFTP interativo.
```
Failed to get ftp directory list for url sftp://example.com:22/. Login denied. Authentication failure.
```
Possíveis causas:
- A chave privada está protegida por uma frase-passe, mas a configuração PrivateKeyPassphrase está faltando na seção [SSH] do jitterbit.conf do agente.
- Uma senha está configurada no endpoint FTP junto com a chave privada. A presença de uma senha nas configurações do endpoint interfere na autenticação baseada em chave.
Resolução:
- Para agentes privados, confirme que a seção [SSH] do jitterbit.conf contém o caminho correto de PrivateKeyFile e, se a chave estiver protegida por frase-passe, o valor correspondente de PrivateKeyPassphrase (consulte Conectando ao SFTP com chaves SSH).
- Na configuração do endpoint FTP, limpe o campo Password quando a autenticação for por chave SSH.
- Confirme que a chave está em um formato suportado pelo agente (OpenSSH). Converta a chave com ssh-keygen se estiver em formato PuTTY (.ppk) ou outro formato não-OpenSSH.

FTP Write: "Usar Renomeação FTP" falha ao gravar em um servidor SFTP

Sintoma: Uma atividade FTP Write configurada com a opção Use FTP Rename falha quando o destino é um servidor SFTP, com um erro similar a:
```
Failed to put ... to the url ...
Quote command returned error. Rename command failed: <reason>.
```
O <reason> é tipicamente No such file or directory, ou Permission denied para um arquivo cujo nome contém caracteres multibyte.
Possíveis causas:
- Em agentes anteriores à versão 11.56, a opção Use FTP Rename não respeitava de forma confiável a etapa de renomeação ao escrever em um servidor SFTP, particularmente em operações com padrão de arquivo.
O nome do arquivo contém caracteres multibyte e o servidor SFTP não suporta renomeação de arquivos cujos nomes os contêm. A partir da versão 12.8 do agent, o conector FTP consegue ler e escrever arquivos com nomes multibyte; porém, com Use FTP Rename o agent faz upload do arquivo com um nome temporário (sufixo -jbupload) e depois o renomeia para o nome final, e se o servidor não conseguir renomear o nome multibyte, retorna uma mensagem enganosa de Permission denied. Nomes de arquivo usando apenas caracteres ASCII não são afetados. Trata-se de uma limitação do servidor SFTP, não do Jitterbit.
Resolução:
- Certifique-se de que o agent está na versão 11.56 ou posterior, onde Use FTP Rename com SFTP funciona conforme esperado. Cloud agents são atualizados automaticamente; atualize private agents se necessário.
- Desmarque a caixa de seleção Use FTP Rename na configuração da atividade para que o agent escreva diretamente no caminho de destino em vez de fazer upload para um nome temporário e renomear. Isso evita a etapa de renomeação e resolve ambas as causas.
- Para o caso multibyte, use alternativamente um servidor SFTP que suporte renomeação de arquivos cujos nomes contêm caracteres multibyte.

SFTP: Anexar ao arquivo não suportado

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

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

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

Sintoma: Conexões File Share que usam caminhos UNC (por exemplo, \\server\share) falham ao conectar quando a operação é executada em um cloud agent.
Possível causa: Cloud agents conseguem resolver caminhos UNC usando um endereço IP público, mas não conseguem resolver nomes de host de servidor em caminhos UNC.
Resolução:
- Substitua o nome do servidor no caminho UNC pelo endereço IP público do servidor (por exemplo, \\192.0.2.1\share).
- Se a resolução de nomes de servidor em caminhos UNC for necessária, use um private agent em vez disso.

Sintoma: Uma atividade Ler do File Share pode falhar ao recuperar arquivos individuais maiores que 2 GB. Arquivos menores são recuperados sem problemas.
Possível causa: O conector File Share tem uma limitação conhecida com arquivos individuais maiores que 2 GB.
Resolução: Nenhuma opção de configuração remove esse limite. Como alternativa, divida o arquivo em segmentos menores na origem para que cada arquivo tenha menos de 2 GB antes que a atividade Ler do File Share o recupere.

Armazenamento local: Não disponível em agentes em nuvem

Sintoma: Uma operação usando um conector Local Storage falha quando executada em um agente na nuvem.
Possível causa: Local Storage acessa o sistema de arquivos da máquina onde o agente está instalado. Agentes na nuvem executam em um ambiente hospedado e não expõem um sistema de arquivos local para esse fim.
Resolução:
- Use agentes privados para qualquer operação que exija o conector Local Storage. Local Storage é desabilitado em agentes privados por padrão, portanto, também ative-o no arquivo de configuração do agente privado (consulte Ativar local de arquivo local).
- Para fluxos de trabalho em agentes na nuvem, substitua Local Storage por Temporary Storage ou um conector de armazenamento externo (File Share, FTP ou Cloud Datastore).

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

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

Armazenamento temporário: Caracteres restritos em caminhos de arquivo

Sintoma: Uma atividade Ler ou Gravar do Temporary Storage falha quando o caminho do arquivo contém certos caracteres especiais.
Possível causa: Os seguintes caracteres não são suportados em caminhos de arquivo do Temporary Storage: ~, %, $, ", <, >, :, ?
Resolução:
- Remova ou substitua os caracteres não suportados no caminho do arquivo. Os seguintes caracteres são suportados: !, @, #, ^, &, *, (, ), [, ], ', ;
- Tanto / quanto \ são aceitos como separadores de caminho.

Armazenamento temporário: Limite de tamanho de arquivo de 50 GB em agentes em nuvem

Sintoma: uma atividade de Gravação de Armazenamento Temporário falha ao gravar arquivos grandes através de um agente na nuvem.
Possível causa: agentes na nuvem impõem um tamanho máximo de arquivo de 50 GB por arquivo para Armazenamento Temporário.
Resolução:
- Use um agente privado para fluxos de trabalho que precisam gravar arquivos individuais maiores que 50 GB no Armazenamento Temporário.
- Se apenas agentes na nuvem estiverem disponíveis, divida grandes conjuntos de dados em múltiplos arquivos menores que 50 GB antes de gravar no Armazenamento Temporário.

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

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

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

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

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

Sintoma: Uma operação HTTP v2 que envia um payload XML para um serviço web SOAP ou XML falha com um erro de servidor (como 500 Internal Server Error) mesmo que o mesmo payload tenha sucesso quando enviado do Postman ou SoapUI. Ao inspecionar o corpo da solicitação recebido pelo destino, verifica-se que as declarações de namespace XML foram consolidadas no elemento raiz e os prefixos de namespace originais foram substituídos por genéricos (por exemplo, soapenv:Envelope se torna Envelope xmlns="...", e os prefixos de elemento são renumerados como ns, ns1, ns2).
Possível causa: Quando um esquema de solicitação personalizado é usado na configuração da atividade HTTP v2, a transformação normaliza o XML por padrão, movendo todas as declarações de namespace para o nó raiz e reatribuindo seus prefixos. Serviços SOAP e outros endpoints XML que validam a consistência de prefixos de namespace rejeitam o payload modificado.
Resolução:
- Na versão do agente 12.8 ou posterior, defina jitterbit.target.xml.preserve.namespace.prefix como true em uma etapa de script anterior à transformação, para manter os prefixos de namespace do XML de origem em vez de reatribuir genéricos:
```
$jitterbit.target.xml.preserve.namespace.prefix = true;
```
- Se seus agentes privados forem anteriores à versão 12.8, ou se o destino também rejeitar a consolidação de declarações de namespace no elemento raiz, use o esquema de solicitação padrão em vez de um personalizado e mapeie o payload XML completo como uma string no campo body do esquema. O payload é então tratado como uma string em vez de XML analisado, portanto suas declarações de namespace são preservadas. O esquema de resposta ainda pode ser um esquema personalizado.

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

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

HTTP v2: Valor JSON em uma variável de projeto de cabeçalho de solicitação falha ao analisar

Sintoma: uma atividade do HTTP v2 que lê um valor de cabeçalho de solicitação de uma variável de projeto contendo uma string JSON falha com um erro de parse:
```
Expected a ',' or ']' at 139 [character 140 line 1]
```
O mesmo JSON funciona quando colado diretamente na coluna Valor da tabela Cabeçalhos de Solicitação.
Possível causa: quando um valor de cabeçalho de solicitação é lido de uma variável de projeto, o conector HTTP v2 não escapa as aspas incorporadas da mesma forma que faz quando você digita o valor diretamente na tabela Cabeçalhos de Solicitação. As aspas não escapadas quebram a string do cabeçalho antes de chegar ao destino.
Resolução:
- Ao armazenar JSON em uma variável de projeto que será usada como valor de cabeçalho, escape cada aspas duplas com uma barra invertida. Por exemplo, armazene o valor como {\"success\": \"true\"} em vez de {"success": "true"}.
- Se o conteúdo JSON for estático, cole-o diretamente na coluna Valor da tabela Cabeçalhos de Solicitação em vez de usar uma variável. O conector aplica o escape necessário nesse caminho.

HTTP e HTTP v2: URL contém vários caracteres `?`

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

HTTP v2: Codificação dupla de URL quando "Encode request URL" está habilitado

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

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

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

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

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

HTTP: Envia `null` como a string `"null"`

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

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

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

LDAP Search Entry: Expressão de filtro é sensível a maiúsculas em alguns servidores

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

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

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

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

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

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

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

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

Sintoma: Uma atividade Update do Microsoft Entra ID falha com:

Um valor foi encontrado com um nome de tipo incompatível com os metadados.
O valor especificou seu tipo como 'Edm.String', mas o tipo especificado nos metadados é 'Edm.DateTimeOffset'.
[HTTP/1.1 400 Bad Request]

Possível causa: O conector envia valores de campo DateTime (como employeeHireDate) sem a anotação @odata.type exigida pela API Microsoft Graph. Sem a anotação, o valor é interpretado como Edm.String em vez de Edm.DateTimeOffset, causando um erro 400.
Resolução:
1. Abra a configuração da atividade Update do Microsoft Entra ID.
2. Na etapa 1, expanda Configurações opcionais e ative Definir tipo OData no payload.
3. Salve a atividade, reimplante e execute novamente a operação.

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

Sintoma: Uma atividade Query do Microsoft Entra ID falha quando uma condição de filtro é aplicada na etapa 3:
```
(Request_UnsupportedQuery) Unsupported or invalid query filter clause specified for property '<property>' of resource '<object>'. [HTTP/1.1 400 Bad Request]
```
A mesma consulta é bem-sucedida quando nenhum filtro é aplicado.
Possível causa: A filtragem em certas propriedades do Microsoft Entra ID (como companyName e createdDateTime) usa a capacidade de consulta avançada da API Microsoft Graph, que requer $count=true na string de consulta. Sem ela, a API rejeita o filtro mesmo quando a sintaxe está correta. O conector inclui automaticamente o cabeçalho ConsistencyLevel: eventual necessário, mas $count=true deve ser adicionado separadamente.
Resolução: Escolha uma das seguintes opções dependendo da aba usada na etapa 3:
- Aba Básica: Marque a caixa de seleção Incluir Contagem. Isso adiciona $count=true à consulta automaticamente.
- Aba Avançada: Acrescente &$count=true à string de filtro manualmente. Por exemplo:
```
$filter=companyName eq 'Example Corp'&$count=true
```

Para a lista de propriedades que exigem sintaxe de consulta avançada, consulte Advanced query capabilities on Microsoft Entra ID objects na documentação do Microsoft Graph.

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

Sintoma: Operações usando o conector Microsoft Dynamics AX contra AX 2012 falham em tempo de execução, mesmo que o teste de conexão seja bem-sucedido no Studio. O log do Jitterbit Dynamics AX 2012 Connector REST Service contém:
```
The server has rejected the client credentials.
```
```
The logon attempt failed
```
Causa: O campo Domain Name na conexão AX 2012 não está definido com o valor correto. A autenticação AX 2012 requer que o Domain Name seja a extensão de domínio DNS (por exemplo, yourcompany.com), não um nome de domínio curto ou NetBIOS. Um valor de domínio incorreto faz com que o AX rejeite credenciais válidas com uma falha de logon, mesmo quando o teste de conexão é bem-sucedido.
Resolução:
1. Abra a conexão Dynamics AX 2012 no Studio.
2. Defina o campo Domain Name para sua extensão de domínio DNS (por exemplo, yourcompany.com), não um nome de domínio curto/NetBIOS.
3. Confirme que o Login é o nome de usuário da conta de serviço AX com os privilégios necessários e reinsira a Password para descartar um valor obsoleto.
4. Teste a conexão e execute novamente a operação.

NetSuite: Erro de URL do data center

Sintoma: Uma conexão NetSuite que anteriormente foi testada com sucesso agora falha com este erro:

Connector Error: Error getting the data center URL.

Caused by: org.jitterbit.integration.server.engine.connector.exception.NetSuiteWebServiceRuntimeException: FaultString:

In this account, you must use account-specific domains with this SOAP web services endpoint. You can use the SOAP getDataCenterUrls operation to obtain the correct domain. Or, go to Setup > Company > Company Information in the NetSuite UI. Your domains are listed on the Company URLs tab.

Em algumas circunstâncias, este erro pode aparecer:

You are not requesting the correct data center for your company.
Causa: Devido a alterações feitas pelo NetSuite, alguns formatos de URL WSDL que eram permitidos anteriormente não são mais aceitos, incluindo URLs WSDL genéricas e específicas do data center. Por exemplo:
- URL WSDL genérica: https://webservices.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
- URL WSDL específica do data center: https://webservices.na3.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
Solução alternativa: Altere a URL do WSDL para usar um domínio específico da conta:
- URL WSDL específica da conta: https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
Para obter instruções sobre como encontrar o domínio específico da conta NetSuite e usá-lo na URL WSDL, consulte Use um URL WSDL específico da conta NetSuite.

NetSuite: `INSUFFICIENT_PERMISSION` apesar do teste de conexão bem-sucedido

Sintoma: Mesmo que o teste de uma conexão NetSuite seja bem-sucedido, você pode receber um erro INSUFFICIENT_PERMISSION ao executar operações que contêm atividades que usam essa conexão.
Solução alternativa: Ao gerar tokens de acesso, use um papel com Acesso Total ou Administrador, ou garanta que as permissões apropriadas estejam habilitadas para o papel utilizado. Instruções detalhadas estão disponíveis na documentação do NetSuite Getting Started with Token-based Authentication.

NetSuite: Conexão com sandbox falha após atualização do sandbox

Sintoma: Uma conexão NetSuite configurada para uma conta de sandbox do NetSuite falha com um erro de autenticação depois que o ambiente de sandbox é atualizado.
Causa: Cada vez que um sandbox do NetSuite é atualizado, todos os tokens de autenticação baseada em token (TBA) associados a esse sandbox são invalidados. A conexão continua usando os tokens antigos, que não são mais aceitos pelo NetSuite.
Resolução: Depois de cada atualização do sandbox, gere novos tokens de TBA para a conta de sandbox e atualize os campos Chave do token e Segredo do token na conexão NetSuite. Para instruções sobre como obter novos valores de token, consulte Coletar valores para usar o TBA do NetSuite.

NetSuite: Campos personalizados não aparecem no esquema da atividade

Sintoma: Campos personalizados de um objeto do NetSuite não estão presentes no esquema de transformação em um agente privado, mesmo que esses campos existam no NetSuite.
Causa: O conector NetSuite expõe campos personalizados para muitos objetos por padrão, mas alguns objetos exigem configuração explícita no arquivo de configuração do conector NetSuite do agente.
Resolução: Adicione o objeto ao arquivo de configuração netsuiteconfig.xml no agente privado. Consulte Expor campos personalizados no conector NetSuite para instruções completas, incluindo como lidar com objetos com mais de 1.000 campos personalizados.

NetSuite: Segmentos personalizados não aparecem ou não são suportados em buscas avançadas

Sintoma: Segmentos personalizados não estão visíveis no esquema da atividade, ou segmentos personalizados do tipo Lista/Registro não estão disponíveis em uma pesquisa avançada.
Causa: Segmentos personalizados exigem permissões específicas na conta de usuário do NetSuite. Além disso, o tipo de segmento Lista/Registro não é suportado em pesquisas avançadas: apenas o tipo Múltipla Seleção é.
Resolução: Consulte Segmentos personalizados na página da atividade de Pesquisa do NetSuite para requisitos de permissão e limitações conhecidas.

NetSuite: Campos de corpo personalizados não visíveis devido a permissão de função ausente

Sintoma: Campos personalizados do corpo de transações (por exemplo, campos adicionados a um registro Sales Order ou outro registro de transação) não aparecem no esquema de saída da atividade de Pesquisa do NetSuite, mesmo que os campos existam na instância do NetSuite e o teste de conexão seja bem-sucedido.
Possível causa: O papel do NetSuite usado pela integração não tem permissão de View para Custom Body Fields. O conector NetSuite chama a ação SOAP getList para recuperar as definições de campos personalizados; uma violação de permissão nessa chamada faz com que os campos sejam totalmente omitidos do esquema.
Resolução:
1. Na sua conta do NetSuite, abra o papel atribuído ao usuário de integração e conceda pelo menos acesso de View à permissão Custom Body Fields.
2. Salve o papel e aguarde alguns minutos para que a alteração de permissão tenha efeito.
3. No Studio, crie uma nova atividade de Pesquisa do NetSuite ou importe o projeto para um novo ambiente de projeto para limpar o esquema em cache. Os campos personalizados do corpo devem agora aparecer no esquema de saída.

Sintoma: Ao configurar uma atividade de Pesquisa do NetSuite usando um tipo de pesquisa Pesquisa Salva, o menu suspenso Selecionar uma Pesquisa Salva aparece vazio ou não lista todas as pesquisas salvas esperadas.
Causa: A API do NetSuite limita as respostas a 1.000 registros por solicitação. Quando um objeto tem mais de 1.000 pesquisas salvas, o menu suspenso não consegue listar todas elas e pode aparecer vazio.
Resolução: Use a opção Fornecer ID do Script da Pesquisa Salva para ignorar o menu suspenso:
1. Na seção Selecionar uma Pesquisa Salva da configuração da atividade, selecione Fornecer ID do Script da Pesquisa Salva.
2. Insira diretamente o ID do script da pesquisa salva de destino. O ID do script pode ser encontrado na interface do NetSuite, na página de detalhes da pesquisa salva.

NetSuite: Botão Testar Consulta de busca expandida está desabilitado

Sintoma: Ao configurar uma pesquisa expandida na atividade de Pesquisa do NetSuite, o botão Testar Consulta aparece acinzentado e não pode ser clicado.
Causa: Uma pesquisa expandida requer uma condição de consulta em um objeto relacionado. O botão Testar Consulta é desativado quando nenhuma condição em um objeto relacionado foi adicionada.
Resolução: Adicione pelo menos uma condição que filtre em um objeto relacionado. Se a pesquisa precisar filtrar apenas nos próprios campos do objeto atual, use o tipo Pesquisa Básica em vez de uma pesquisa expandida.

NetSuite: Campos de fórmula de busca salva estão faltando na saída da atividade

Sintoma: Uma atividade de Pesquisa do NetSuite que usa uma pesquisa salva retorna a contagem de registros esperada em Testar Consulta, mas colunas baseadas em fórmula ou de junção complexa (por exemplo, campos customSearchJoin) estão ausentes na saída da atividade e no mapeamento da transformação, mesmo que essas colunas apareçam na pesquisa salva na interface do NetSuite.
Causa: Colunas de pesquisa salva baseadas em fórmula são calculadas no nível da interface do NetSuite e não estão incluídas na resposta SOAP que o conector lê. Como resultado, esses valores não aparecem na saída da atividade mesmo que a pesquisa retorne registros.
Resolução:
1. Quando possível, reconstrua a pesquisa salva usando campos armazenados (não baseados em fórmula), já que valores calculados por fórmula podem não ser retornados pela API.
2. No Studio, abra a atividade de Pesquisa do NetSuite e, na primeira página de configuração, selecione a opção Pesquisa Salva (usar definição de pesquisa reutilizável anteriormente salva no NetSuite).
3. Selecione a pesquisa salva no menu suspenso Selecionar uma Pesquisa Salva.
4. Percorra as páginas restantes e execute a operação para recuperar os dados completos.

NetSuite: Erro de análise de Testar Consulta quando o filtro usa uma variável de projeto

Sintoma: Quando um filtro de uma atividade de Pesquisa do NetSuite usa uma variável de projeto para um valor de data ou data/hora (como lastModifiedDate), clicar em Testar Consulta na configuração da atividade retorna um erro 500 referenciando um formato de data inválido. A mesma operação é executada com sucesso em tempo de execução.
```
Connector Error: FaultString: java.text.ParseException: Invalid dateTime format: [lastModifiedDate]
```
Causa: Testar Consulta não resolve variáveis de projeto. Ele envia a referência literal da variável (por exemplo, [lastModifiedDate]) como o valor do filtro, que o NetSuite rejeita como uma data inválida. Em tempo de execução, o agente substitui o valor real da variável, então a própria operação é bem-sucedida.
Resolução: Para testar ou salvar alterações na atividade sem remover a variável, adicione um valor padrão temporário à referência da variável na condição de filtro:
1. No filtro, altere a referência da variável de [my_date_variable] para [my_date_variable{2023-01-01T00:00:00.000Z}] (usando a data/hora ISO 8601 apropriada como padrão).
2. Clique em Testar Consulta. O teste agora é bem-sucedido porque uma data válida é substituída no lugar da variável não resolvida.
3. Salve quaisquer outras alterações na atividade. O valor padrão pode permanecer; em tempo de execução, o agente sempre usa o valor atual da variável de projeto.

NetSuite: Busca salva com campos de resultado como saída requer agente 11.49 ou posterior

Sintoma: Na atividade de Pesquisa do NetSuite, a opção Pesquisa Salva com campos de resultado como saída está visível na interface da atividade, mas as operações que a utilizam falham com um erro 500 quando executadas em um agente privado mais antigo.
Causa: O recurso Pesquisa Salva com campos de resultado como saída foi introduzido na versão 11.49 do agente. Agentes privados em versões anteriores exibem a opção na interface, mas não têm suporte em tempo de execução para executá-la.
Resolução:
1. Confirme a versão do agente na página Agentes do Management Console.
2. Atualize os agentes privados para a versão 11.49 ou posterior para usar essa opção. Os agentes de nuvem são mantidos atualizados automaticamente.
3. Se não for possível atualizar o agente privado, reconfigure a atividade para usar Pesquisa Salva em vez disso. Esse modo é suportado em versões de agente anteriores.

NetSuite: Atividade de atualização retorna `INVALID_KEY_OR_REF` quando XML de origem perde `internalId`

Sintoma: Uma atividade Atualização do NetSuite é concluída sem gerar uma exceção, mas nenhum registro é atualizado no NetSuite. O payload de resposta contém o status SOAP INVALID_KEY_OR_REF. O problema geralmente aparece quando um script de transformação usa GetXMLString para construir o payload de atualização a partir de uma resposta de pesquisa anterior.

<writeResponse>
  <platformCore:status isSuccess="false">
    <platformCore:statusDetail type="ERROR">
      <platformCore:code>INVALID_KEY_OR_REF</platformCore:code>
      <platformCore:message>The specified key is invalid.</platformCore:message>
    </platformCore:statusDetail>
  </platformCore:status>
  <baseRef>
    <platformCore:RecordRef type="invoice"></platformCore:RecordRef>
  </baseRef>
</writeResponse>

Causa: GetXMLString serializa um nó XML, mas não preserva atributos no elemento raiz. Quando o internalId do registro de origem é mantido como um atributo no nó raiz do registro do NetSuite (por exemplo, no elemento Invoice), ele é removido da string resultante e a atividade Atualização vê uma referência de registro vazia.
Resolução: Capture o internalId do registro de origem separadamente e, em seguida, adicione-o de volta ao XML serializado antes de passar o payload para a atividade Atualização:
1. No script de transformação, atribua o internalId de origem a uma variável.
2. Chame GetXMLString para construir o XML do registro.
3. Use Replace para injetar internalId="..." no elemento raiz. Para um registro Invoice:
```
<trans>
$invoiceInternalId = searchResponse$searchResult$recordList$record.Invoice$internalId;
$MyRecord = GetXMLString([searchResponse$searchResult$recordList$record.]);
$MyRecord = Replace($MyRecord, "<Invoice>", '<Invoice internalId="' + $invoiceInternalId + '">');
</trans>
```
4. Passe MyRecord para a próxima etapa.

NetSuite: Operações falham devido a limites de registros da API

Sintoma: Uma operação que usa o conector NetSuite falha ou processa menos registros do que o esperado porque os dados de origem excedem o limite de registros por chamada imposto pela API do NetSuite.
Causa: A API do NetSuite impõe limitações de tamanho no número de registros por solicitação. Quando mais registros são enviados em uma única chamada do que o limite permite, o NetSuite rejeita o excesso.
Resolução:
1. Habilite o particionamento na operação em Opções de operação. Quando a origem é uma atividade do NetSuite, o particionamento divide os dados durante a transformação, e não na recuperação. Cada pedaço é gravado em um arquivo temporário e os arquivos são combinados no destino final depois que todos os pedaços são processados.
2. Quando o destino é uma atividade do NetSuite, cada pedaço de origem produz um pedaço de destino, com a transformação aplicada separadamente a cada um. Os pedaços de destino resultantes são então combinados.
3. Para instruções e melhores práticas, consulte Habilitar Chunking.
4. Para referência mais detalhada, consulte Informações detalhadas sobre chunking.

NetSuite: Limite de solicitações simultâneas excedido

Sintoma: Operações de alto volume do NetSuite falham com um dos seguintes erros:
- Solicitações RESTlet: HTTP error code: 400 Bad Request / SuiteScript error code: SSS_REQUEST_LIMIT_EXCEEDED
- Solicitações de serviços web: ExceededConcurrentRequestLimitFault ou ExceededRequestLimitFault
Causa: O NetSuite impõe governança de simultaneidade por conta, limitando o total combinado de solicitações simultâneas de serviços web e RESTlet. O limite depende do seu nível de serviço e do número de licenças SuiteCloud Plus. Por exemplo, o Nível de Serviço 1 com cinco licenças SuiteCloud Plus permite 65 solicitações simultâneas (15 + (5 × 10)). Exceder esse limite faz com que o NetSuite rejeite o excesso de solicitações.
Resolução:
1. Para agentes privados, defina MaxNumberOfOperationThreads na seção [OperationEngine] do arquivo jitterbit.conf para um valor que mantenha o total de solicitações simultâneas do NetSuite dentro do limite de governança da sua conta.
2. Projete as operações para serializar solicitações quando possível, ou implemente lógica de nova tentativa que aguarde e tente novamente quando a resposta WS_CONCUR_SESSION_DISALLOWED for recebida.
3. Revise seus aplicativos cliente NetSuite para confirmar que eles lidam com os códigos de erro de simultaneidade adequadamente.
4. Para mais detalhes sobre os limites de governança por nível, consulte as notas de versão do NetSuite 2017.2 (páginas 71 e 72).

NetSuite: Operações falham após atualizar a URL do WSDL

Sintoma: Depois de atualizar a URL de download do WSDL em uma conexão NetSuite para referenciar uma versão mais recente do WSDL, todas as operações que usam as atividades dessa conexão falham em tempo de execução.
Causa: Alterar a URL de download do WSDL atualiza a conexão, mas não atualiza os esquemas de dados usados pelas transformações existentes. As transformações continuam referenciando campos de esquema da versão anterior do WSDL, que são incompatíveis com a nova versão.
Resolução: Para atualizar a versão do WSDL corretamente, siga as etapas em Alterar a versão do WSDL. Este procedimento atualiza tanto a URL da conexão quanto os esquemas de dados usados por todas as atividades afetadas, evitando falhas em tempo de execução causadas por incompatibilidades de esquema.

NetSuite Create, Update ou Upsert falha com "is not a legal value for Country"

Sintoma: Uma atividade NetSuite Create, Update ou Upsert falha quando o valor de origem de um campo de país não corresponde a um valor enum Country do NetSuite:
```
FaultString: org.xml.sax.SAXException: <country_value> is not a legal value for {urn:types.common_<version>.platform.webservices.netsuite.com}Country
```
Possível causa: A API SuiteTalk do NetSuite exige que Country (e outros campos enumerados) seja um dos valores enum predefinidos do WSDL (por exemplo, _unitedStates). Um nome de país exibido, um código de país ISO ou qualquer valor que não corresponda exatamente ao enum do WSDL é rejeitado.
Resolução:
- Na transformação que mapeia para o destino do NetSuite, traduza o valor de país de origem para o valor enum correspondente do NetSuite antes de escrever. Um dicionário de referência cruzada, uma instrução Case ou uma tabela de consulta funcionam para isso.
- Construa a referência cruzada a partir do enum Country definido no WSDL SuiteTalk do NetSuite que seu conector está usando. Os valores válidos mudam entre versões do WSDL, portanto, sempre verifique em relação à versão do WSDL configurada atualmente na conexão.
- Aplique a mesma abordagem a qualquer outro campo apoiado por um enum do NetSuite (por exemplo, State, Currency) onde os valores de origem ainda não correspondem ao enum do WSDL.

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

Sintoma: Configurar uma atividade Query do OData que aponta para um serviço OData v2.0 retorna um erro ao buscar a lista de objetos, mesmo que o teste de conexão seja bem-sucedido:
```
An error occurred while fetching the data:
Error while generating for query activity object list. The Exception is No entity sets found for the address provided.
```
Possível causa: O suporte para serviços OData V2 foi adicionado ao conector OData na versão 11.59 do agente, através da configuração de conexão OData version. Em agentes anteriores à versão 11.59, o conector suporta apenas OData V4, portanto, uma conexão apontada para um serviço OData V2 não consegue preencher a lista de objetos. A mesma falha ocorre na versão 11.59 ou posterior se OData version for deixado em V4 para um serviço OData V2.
Resolução:
1. Para agentes privados, atualize para a versão 11.59 ou posterior. Os agentes em nuvem recebem a atualização automaticamente.
2. Na conexão OData, defina OData version como V2 (o padrão é V4). Salve e teste novamente a conexão.
3. Reabra a atividade Query do OData. Os conjuntos de entidades devem ser carregados agora.

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

Sintoma: Uma conexão OData com um endpoint Microsoft Dynamics 365 Finance and Operations retorna dados apenas da empresa padrão do usuário, portanto, registros de outras empresas estão faltando nos resultados.
Possível causa: Por padrão, um endpoint OData do Dynamics 365 Finance and Operations retorna apenas os dados que pertencem à empresa padrão do usuário. Para dar à conexão um escopo entre empresas (expandido), uma cláusula de filtro entre empresas deve ser anexada à URL de metadados OData da conexão (a URL $metadata). Na URL de metadados, ?cross-company=true por si só não aplica o escopo expandido.
Resolução: Na conexão OData, anexe uma cláusula de filtro dataAreaId à URL de metadados OData, substituindo usrt pelo seu identificador de área de dados e, em seguida, salve e teste novamente:
```
?$filter=dataAreaId eq 'usrt'&cross-company=true
```
Para mais informações sobre como o Dynamics 365 delimita dados OData por empresa, consulte a documentação da Microsoft sobre comportamento entre empresas.

Oracle EBS: Erro de conexão "custom provider JAR file is not present"

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

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

Possível causa: O conector Oracle EBS requer que o driver JDBC do Oracle (ojdbc8.jar) seja colocado manualmente no agente privado. Este arquivo não é incluído no agente e deve ser adicionado antes que a conexão seja bem-sucedida.
Resolução:
1. Baixe ojdbc8.jar do site da Oracle (é necessária uma conta Oracle).
2. Coloque ojdbc8.jar no diretório $JITTERBIT_HOME/Connectors/Providers/ no host do agente privado.
3. Reinicie todos os agentes no grupo de agentes.
4. Teste novamente a conexão do Oracle EBS.

Salesforce: Operações falham devido aos limites de registros da API

Sintoma: Uma atividade padrão do Salesforce (como Upsert) falha ou processa menos registros do que o esperado porque os dados de origem excedem o limite de registros por chamada. A operação pode falhar com:
```
EXCEEDED_ID_LIMIT: record limit reached. cannot submit more than 200 records into this call
```
Causa: As atividades padrão do Salesforce aceitam um máximo de 200 registros por chamada. Quando mais registros são enviados em uma única chamada, o Salesforce rejeita o excesso. Isso pode aconter de duas formas: o chunking não está ativado ou está ativado mas a origem não consegue respeitá-lo. O chunking é respeitado apenas quando a origem é um conector nativo. Com qualquer outra origem, como HTTP v2, todos os registros são enviados em uma única chamada independentemente do tamanho de chunk configurado. Consulte Chunking requer um conector nativo como origem.
Resolução:
- Ative o chunking na operação e defina o tamanho do chunk para 200 ou menos. Para obter instruções, consulte Ativar Chunking.
- Confirme que o tamanho do chunk é realmente aplicado aos dados de origem. Quando a origem é um payload grande produzido por outra atividade, verifique se a operação o divide em chamadas de 200 registros ou menos. Se o limite ainda for excedido apesar de um tamanho de chunk correto, entre em contato com o suporte Jitterbit.
- Para atividades em massa do Salesforce, aumente o tamanho de chunk padrão de 200 para um valor maior, como 10.000, pois as atividades em massa são projetadas para lidar com altos volumes de registros.

Chunking divide os dados durante a transformação em vez de na recuperação. Quando a origem é uma atividade do Salesforce, cada chunk é gravado em um arquivo temporário e os arquivos são combinados no destino final após todos os chunks serem processados. Quando o destino é uma atividade do Salesforce, cada chunk de origem produz um chunk de destino, com a transformação aplicada separadamente a cada um, e os chunks de destino resultantes são então combinados. Para mais detalhes, consulte Informações detalhadas sobre chunking.

Salesforce, Service Cloud e ServiceMax: Autenticação multifator impede conexões com autenticação básica

Sintoma: Uma conexão que usa Autenticação Básica com o conector Salesforce, Salesforce Service Cloud ou ServiceMax falha no teste de conexão ou se conecta mas falha em operações com um erro de autenticação.
Causa: Esses conectores compartilham a mesma base de código e autenticam em uma org do Salesforce. A autenticação básica requer uma conta do Salesforce cujo conjunto de permissões atribuído não inclui a permissão Autenticação Multifator para Logins de API. Quando essa permissão é atribuída (MFA ativa para a conta), as conexões de autenticação básica falham.
Resolução:
- No Salesforce, revise o conjunto de permissões atribuído ao usuário de login de integração do sistema e confirme que Autenticação Multifator para Logins de API não está selecionado. Os tipos de login de integração do sistema estão isentos do requisito de MFA do Salesforce. Para detalhes, consulte as Perguntas frequentes sobre autenticação multifator do Salesforce.
- Se não for possível remover MFA do usuário de integração, mude a conexão para autenticação OAuth 2.0 de dois passos.

Nota

O uso de OAuth 2.0 de dois passos requer versão do agente 11.59 ou posterior. Em agentes 12.x, requer 12.3 ou posterior para o conector Salesforce e 12.4 ou posterior para os conectores Salesforce Service Cloud e ServiceMax.

Certificado Salesforce: Incompatibilidade de Subject Alternative Name (SAN)

Sintoma: Uma conexão Salesforce com uma sandbox ou uma org com Domínios Aprimorados ativados falha com:
```
Certificate for <url> doesn't match any of the subject alternative names
```
Possíveis causas:
- O certificado não inclui o MyDomain do Salesforce ou a URL da sandbox em seus Nomes Alternativos do Assunto.
- A caixa de seleção Sandbox nas configurações de conexão do Salesforce não está corretamente ativada.
Resolução:
- Inspecione as entradas SAN do certificado usando OpenSSL: openssl x509 -in cert.crt -text -noout. Confirme que a seção Nome Alternativo do Assunto inclui sua URL do MyDomain do Salesforce.
- Nas configurações de conexão do Salesforce no Studio, verifique se a caixa de seleção Sandbox está corretamente definida para sua org de destino.
- Se a URL do Salesforce estiver ausente dos SANs, regenere o certificado para incluir o domínio específico.
- Se a mesma conexão funciona em um grupo de agentes na nuvem mas falha em um agente privado, a causa pode ser uma extensão SNI ausente no handshake TLS do agente. Consulte Falha na conexão da sandbox do Salesforce com incompatibilidade de certificado.

Conexão, configuração ou operação do Salesforce falha intermitentemente com `SERVER_UNAVAILABLE`

Sintoma: Um teste de conexão, configuração de atividade ou execução de operação do Salesforce falha intermitentemente com:
```
SERVER_UNAVAILABLE: server temporarily unavailable
```
Por exemplo, isso pode ocorrer ao selecionar um objeto durante a configuração de atividade.
Possível causa: O Salesforce retorna este código de falha quando seu próprio servidor está temporariamente incapaz de processar a solicitação; o conector o relata com esta mensagem genérica em vez de passar qualquer texto mais específico do Salesforce.
Resolução: Repita o teste de conexão, a etapa de configuração ou a operação, aguardando mais tempo entre cada tentativa se continuar falhando. Se o erro persistir ou ocorrer com frequência, verifique Salesforce Trust para um incidente relatado que afete sua instância ou entre em contato com o Suporte do Salesforce. Um cenário relacionado é descrito no artigo do Salesforce SERVER_UNAVAILABLE: Too Many Requests Waiting for Connections.

Salesforce: Esquema de dados não inclui campos adicionados recentemente

Sintoma: Um campo adicionado recentemente a um objeto do Salesforce não aparece no esquema de transformação ao configurar uma atividade do Salesforce.
Causa: O esquema de dados é armazenado em cache desde quando a atividade foi configurada pela última vez e não é atualizado automaticamente.
Resolução: Abra a configuração de atividade e avance por cada etapa. Faça pelo menos uma pequena alteração (como adicionar e remover um caractere do nome da atividade) para forçar um recarregamento do esquema. Clique em Finished para salvar a configuração atualizada.

Salesforce: Automap não mapeia campos quando uma atividade do Salesforce é o destino

Sintoma: Quando uma atividade do Salesforce (como Insert ou Upsert) é usada como alvo de uma transformação, usar Automap não mapeia nenhum campo.
Causa: O esquema de atividade do Salesforce inclui um nó raiz extra acima dos campos do objeto quando o esquema é espelhado. Este nó raiz extra impede que o automap corresponda aos campos de origem com os campos de destino corretos.
Resolução:
1. Na tela de transformação, localize o nó de objeto de nível superior no lado do destino (por exemplo, Account).
2. Arraste o nó de origem correspondente para alinhá-lo manualmente.
3. Com os nós alinhados, execute Automap novamente. Os campos sob o nó serão mapeados automaticamente.

Atividade Salesforce Query: Consulta pai-filho gera esquema hierárquico

Sintoma: Uma atividade de Consulta do Salesforce usando uma consulta SOQL pai-filho gera um esquema de resposta hierárquico. Quando este esquema é espelhado no lado do destino de uma transformação, a saída é XML hierárquico em vez de uma estrutura plana.
Causa: O esquema hierárquico reflete a relação pai-filho na consulta. Espelhar o esquema de origem no destino da transformação preserva essa hierarquia na saída.
Resolução:
- Para produzir saída plana, defina um esquema plano no lado do destino da transformação em vez de espelhar o esquema de origem.
- Se acessar resultados de consulta em um script, os dados já estão disponíveis como uma estrutura plana sem qualquer configuração adicional.

Salesforce: Upsert falha para alguns registros (ID externo duplicado)

Sintoma: Uma operação Upsert ou Bulk Upsert do Salesforce é concluída, mas relata falhas para alguns registros.
Causa: Múltiplos registros de origem compartilham o mesmo valor de ID externo. Quando o ID externo não é único, o Salesforce retorna um erro e o upsert falha para esses registros.
Resolução:
- Verifique o arquivo de falha na página Runtime do Management Console (aba Activity Logs) para identificar quais registros falharam.
- Garanta que o campo usado como ID externo tenha um valor único para cada registro. Consulte Criar um ID externo do Salesforce para Jitterbit.

Atividade Salesforce Insert ou Update: Campo Record ID não pode ser mapeado

Sintoma: Uma transformação inclui um mapeamento para o campo de ID de registro do Salesforce em uma atividade Insert ou Update, mas a operação não utiliza o valor mapeado.
Causa: O campo de ID de registro do Salesforce não pode conter um mapeamento nas atividades Insert e Update. O Salesforce atribui o ID de registro automaticamente na inserção; a atividade Update identifica registros pelo ID do Salesforce existente, que não é um campo de destino mapeável.
Resolução: Remova o mapeamento para o campo de ID de registro da transformação. Se o objetivo é atualizar um registro específico pelo seu ID do Salesforce, verifique se os dados de origem fornecem esse ID e se a atividade Update está configurada para corresponder registros com base nele.

Atividades de escrita em massa do Salesforce: Primeiro registro de dados ignorado quando a origem não tem linha de cabeçalho

Sintoma: Uma atividade de escrita em massa do Salesforce (Bulk Insert, Bulk Upsert, Bulk Update, Bulk Delete ou Bulk Hard Delete) é executada sem erro, mas menos registros do que o esperado são gravados no Salesforce. Quando a origem contém apenas um registro de dados, nenhum registro é gravado.
Causa: As atividades de escrita em massa do Salesforce sempre tratam a primeira linha de dados de origem como a linha de cabeçalho de coluna. Esse comportamento não pode ser alterado. Se o arquivo de origem não incluir uma linha de cabeçalho dedicada, o primeiro registro de dados é consumido como cabeçalho e não é gravado no Salesforce.
Resolução:
- Garanta que os dados de origem incluam uma linha de cabeçalho como primeira linha. Os valores do cabeçalho devem corresponder aos nomes de coluna definidos no mapeamento de campos da atividade.
- Verifique se as linhas de dados começam na segunda linha, imediatamente após o cabeçalho.

Etapas de operação da atividade em massa do Salesforce aparecem como "Incomplete" sem dados de entrada ou saída

Sintoma: Ao visualizar um log de operação que inclui uma atividade em massa do Salesforce (Bulk Insert, Bulk Upsert, Bulk Update, Bulk Delete ou Bulk Hard Delete), a entrada de etapa de operação da atividade em massa mostra um status de Incompleto e não exibe dados de entrada ou saída, mesmo quando a operação foi concluída com sucesso e registros foram processados.
Causa: As atividades em massa do Salesforce não geram dados de entrada e saída de componente no log de operação. O status Incompleto na etapa de atividade e a ausência de dados de entrada e saída são comportamentos esperados para todas as atividades em massa, independentemente de o processamento ter sido bem-sucedido.
Resolução:
- Para determinar se registros foram processados e se ocorreram erros, verifique as entradas de texto no log de operação para mensagens de erro ou confirmação de processamento bem-sucedido.
- Para agentes privados, também é possível baixar resultados detalhados por registro: no Management Console, acesse a página Runtime, selecione a execução, abra a aba Activity Logs e baixe o arquivo de resultados.

Atividades em massa do Salesforce falham quando acionadas por uma solicitação de API ou SOAP

Sintoma: Uma atividade em massa do Salesforce (Bulk Query, Bulk Update, Bulk Insert, Bulk Upsert, Bulk Delete ou Bulk Hard Delete) falha imediatamente na inicialização com:
```
Failed to initialize the operation: Failed to get the operation with OperationID = [ID].
A database exception occurred. The reported error was:
ERROR: null value in column "organization_id" of relation "bulkloadinstancetab" violates not-null constraint
```
A mesma atividade em massa é executada sem problemas quando acionada independentemente ou por outros meios.
Possível causa: Operações acionadas por uma solicitação de API ou SOAP (como um fluxo de mensagem de saída do Salesforce) não oferecem suporte a atividades em massa do Salesforce. Neste contexto, o ID da organização não está disponível para o subsistema de carregamento em massa, causando a falha de restrição do banco de dados na inicialização.
Resolução: Substitua a atividade em massa pela atividade padrão equivalente do Salesforce em operações que fazem parte de uma cadeia acionada por API ou SOAP. Por exemplo, substitua uma Bulk Query por uma atividade padrão de Query ou uma Bulk Update por uma atividade padrão de Update. As atividades padrão funcionam corretamente neste contexto.

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

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

Eventos do Salesforce: Limitações da atividade de escuta

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

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

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

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

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

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

JCoException occurred No RFC authorization for function module BAPI_TRANSACTION_COMMIT

Possíveis causas:
- A conta de usuário SAP na conexão não possui autorização S_RFC para BAPI_TRANSACTION_COMMIT ou seus grupos de função relacionados.
- O módulo de função BAPI_TRANSACTION_COMMIT não está configurado como habilitado para remoto no sistema SAP.
- A transformação de solicitação anterior à atividade não define o campo de controle de confirmação.
Resolução:
- No sistema SAP, confirme que o módulo de função BAPI_TRANSACTION_COMMIT está habilitado para remoto.
- Na transformação de solicitação que precede a atividade SAP RFC, defina o campo BAPI_COMMIT como true.
- Verifique se a conta de usuário SAP referenciada na conexão possui autorização S_RFC para BAPI_TRANSACTION_COMMIT e todos os grupos de função relacionados.
- Se o problema persistir, entre em contato com seu administrador SAP BASIS para revisar as atribuições de objeto de autorização do usuário.

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

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

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

Possível causa: O código de Idioma configurado no endpoint SAP não é válido para o sistema SAP de destino: o código não está instalado ou não é suportado nesse sistema, ou está digitado incorretamente ou com capitalização incorreta (por exemplo, en em vez de EN). O SAP rejeita a chave inválida ao inicializar o ambiente de texto do destino.
Resolução:
1. Edite o endpoint SAP no Studio e defina o campo Idioma como um código de idioma de duas letras suportado (por exemplo, EN para inglês).
2. Verifique se o valor corresponde a um idioma instalado e ativo no sistema SAP de destino. Se não tiver certeza, confirme o idioma padrão do usuário de integração no perfil de usuário SAP e use esse.
3. Teste a conexão no Studio para confirmar que a inicialização é bem-sucedida antes de reimplantar a operação.

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

Sintoma: Operações que usam o conector ServiceNow executam lentamente em dois cenários:
- Em agentes privados, a primeira operação após a reinicialização do agente pode levar vários minutos; as execuções subsequentes são rápidas.
- Em agentes na nuvem, as execuções são intermitentemente lentas, levando minutos sempre que o cache de metadados do conector é atualizado.
Isso pode causar timeouts de API a jusante.
Possível causa: O conector armazena em cache os metadados do ServiceNow de forma agressiva. Após uma reinicialização do agente em um agente privado (ou em cada execução para um agente na nuvem que não preservou o cache), a primeira operação deve reconstruir o cache, o que leva vários minutos.
Resolução:
- Em um agente privado, mitigue a lentidão pós-reinicialização adicionando getcolumnsmetadata=onUse às Opções Avançadas do endpoint do ServiceNow. Esta configuração é eficaz apenas em agentes privados.
- Para desempenho consistente em agentes na nuvem, chame a API REST do ServiceNow através do conector HTTP v2 em vez de usar o conector ServiceNow. O conector HTTP v2 não armazena metadados em cache e evita o atraso de reconstrução.

ServiceNow v2: Um objeto não está listado pelo seu nome de conector ServiceNow

Sintoma: Um objeto que é selecionável por um nome familiar no conector ServiceNow não pode ser encontrado por esse mesmo nome no conector ServiceNow v2.
Causa: O uso da API REST do ServiceNow pelo conector ServiceNow v2 expõe objetos usando o nome real da tabela de backend do ServiceNow, que pode diferir do nome usado para o mesmo objeto no conector ServiceNow. Por exemplo, o objeto chamado System no conector ServiceNow corresponde a Sys no conector ServiceNow v2.
Resolução: No ServiceNow, procure o nome real da tabela do objeto em System Definition > Tables e, em seguida, procure esse nome na configuração de atividade do conector ServiceNow v2.

Shopify: As seleções de objeto de atividade podem mudar após atualização da versão da API

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

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

Sintoma: Uma atividade Snowflake Query falha com o seguinte erro quando a consulta retorna um grande número de linhas:
```
Error executing query activity. Exception is Java heap space
```
O conector relata o erro neste formato porque envolve o erro Java subjacente, que aparece mais abaixo no rastreamento de pilha:
```
Caused by: java.lang.OutOfMemoryError: Java heap space
```
Se esse erro ocorrer em consultas que retornam poucas linhas, ou o mesmo agente também falhar com erros de heap através de outros conectores, a causa é mais provável a alocação geral de heap do agente do que o tamanho do conjunto de resultados. Consulte Java heap space: OutOfMemoryError.
Possível causa: O conector Snowflake carrega todo o conjunto de resultados da consulta na memória JVM antes de passá-lo para a transformação. Com conjuntos de resultados muito grandes, isso esgota o heap JVM do Tomcat no agente privado.

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

Sintoma: Em um agente privado executando a versão 12.x, operações que consultam o Snowflake por meio de um driver JDBC do Snowflake (uma conexão de Banco de Dados ou um script DBExecute) falham em tempo de execução, mesmo que o teste de conexão seja bem-sucedido. O erro faz referência à camada de memória Arrow do driver, por exemplo:

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

ou:

JDBC driver internal error: exception creating result java.lang.NoClassDefFoundError: Could not initialize class net.snowflake.client.jdbc.internal.apache.arrow.memory.RootAllocator

Possível causa: Por padrão, o driver JDBC do Snowflake retorna resultados de consultas no formato Apache Arrow, que não é compatível com a versão 12.x do agente e posteriores. Consulte o artigo de solução de problemas do Snowflake sobre esse erro de módulo Java para mais detalhes. O teste de conexão não retorna nenhum conjunto de resultados, portanto ainda passa enquanto as consultas falham. Atualizar a versão do driver JDBC não resolve o problema.
Resolução: Defina enableArrowResultFormat como false e jdbc_query_result_format (ou JDBC_QUERY_RESULT_FORMAT) como json para que o driver retorne resultados em JSON em vez de Arrow:
- Conector de Banco de Dados: Adicione enableArrowResultFormat=false&jdbc_query_result_format=json à string de conexão do Snowflake, no campo Parâmetros Adicionais da String de Conexão (ou no campo String de Conexão, se Usar String de Conexão estiver selecionado).
- Conector Snowflake: Em Configurações opcionais > Propriedades Personalizadas de Conexão, adicione enableArrowResultFormat com um valor de false. Uma linha JDBC_QUERY_RESULT_FORMAT com um valor de JSON já está presente lá por padrão.
Em seguida, salve, teste novamente a conexão e execute a operação novamente.

Em um agente privado, você pode aplicar a correção no nível da JVM para que não precise ser repetida por conexão, adicionando --add-opens=java.base/java.nio=ALL-UNNAMED a CATALINA_OPTS:
LinuxWindowsDocker
Adicione a seguinte linha a /opt/jitterbit/tomcat/bin/setenv.sh:
export CATALINA_OPTS="$CATALINA_OPTS --add-opens=java.base/java.nio=ALL-UNNAMED"
Em seguida, reinicie o agente.
1. Abra o Editor do Registro e localize a seguinte chave:
  
  HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\Jitterbit Tomcat Server\Parameters\Java
2. Abra a subchave Options.
3. No campo Value data, adicione --add-opens=java.base/java.nio=ALL-UNNAMED às opções Java existentes.
4. Clique em Ok.
5. Reinicie o agente.
Use uma das seguintes estratégias para aplicar a configuração:
1. Atualize o Dockerfile e recrie a imagem Docker:
  
  docker build -t my-agent .
2. Inclua na linha de comando do Docker run:
  
  docker run -e CATALINA_OPTS="--add-opens=java.base/java.nio=ALL-UNNAMED" my-agent
3. Inclua em docker-compose.yml e reinicie o contêiner:
  
  environment: - CATALINA_OPTS=--add-opens=java.base/java.nio=ALL-UNNAMED

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

Sintoma: Operações que se conectam ao Snowflake usando o tipo de autenticação Senha (Descontinuada) começaram a falhar após funcionarem anteriormente, por exemplo com:

HttpErrorResponse: Error opening connection. Exception is Failed to authenticate: MFA authentication is required, but none of your current MFA methods are supported for programmatic authentication.

Possível causa: O Snowflake está descontinuando a autenticação de fator único (apenas senha), incluindo contas do tipo LEGACY_SERVICE necessárias para este tipo de autenticação. O Snowflake migra contas LEGACY_SERVICE para TYPE=SERVICE de forma gradual, por conta, o que bloqueia completamente a autenticação baseada em senha; algumas contas também têm autenticação multifator (MFA) ativada, que é incompatível com esta conexão totalmente automatizada e programática, já que MFA requer intervenção humana. Consulte Senha (Descontinuada) para a linha do tempo de descontinuação.
Resolução: Atualize a conexão do conector Snowflake no Studio para usar autenticação OAuth ou Chave-Par e configure a conta de usuário do Snowflake para corresponder, garantindo que ela não esteja inscrita em MFA.

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

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

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

Sintoma: Uma atividade Query do Snowflake usando um esquema simples falha em tempo de execução com:
```
StartElement() error, starting element does not match with the root.
qName= "<table_name_lowercase>", root name="<TABLE_NAME_UPPERCASE>"

ProcessFlatStream error
```
Este erro ocorre quando a consulta inclui uma cláusula WHERE, uma cláusula LIMIT ou uma referência de variável em uma cláusula WHERE.
Possível causa: O conector Snowflake retorna o nome da tabela em minúsculas na resposta XML. Quando o Studio gera um esquema simples a partir da consulta, o nome do nó raiz é criado em maiúsculas. A incompatibilidade de maiúsculas e minúsculas entre o nó raiz do esquema (maiúsculas) e o nó raiz da resposta XML (minúsculas) causa a falha do processamento de fluxo simples.
Resolução: Escolha uma das seguintes opções:
- No esquema simples, altere o nome do nó raiz para minúsculas para corresponder à saída do conector. Por exemplo, renomeie SALES_ORDERS para sales_orders.
- Use o esquema espelho com mapeamento padrão em vez de um esquema simples construído manualmente. O esquema espelho deriva sua estrutura diretamente da resposta do conector e não tem esta incompatibilidade de maiúsculas e minúsculas.

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

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

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

Sintoma: Uma atividade Snowflake Insert ou Merge falha com um erro de compilação SQL como:
```
SQL compilation error:
syntax error line 1 at position <n> unexpected '<token>'.
```
Os valores das colunas também podem aparecer mapeados incorretamente, com dados de um campo aparecendo na coluna errada.
Possíveis causas:
- Valores de campo contendo aspas simples (por exemplo, um valor como corner's) não são escapados antes de serem incluídos na carga SQL. A aspa não escapada encerra a string prematuramente, fazendo com que o restante do valor seja interpretado como sintaxe SQL em vez de dados.
- Um nome de coluna de destino contém um caractere especial, como um hífen (por exemplo, Zip-Code). O Snowflake exige que um identificador contendo um caractere especial seja citado; sem aspas, produz um erro de sintaxe no hífen.
Resolução:
- Para valores contendo aspas simples: Nas Configurações opcionais da conexão do Snowflake, ative Escape special characters. Isso escapa automaticamente as aspas simples nas cargas das atividades Insert e Invoke Stored Procedure. Para atividades Merge ou como alternativa para Insert, use SQLEscape no mapeamento de transformação para escapar as aspas simples nos valores de campo afetados antes de chegarem à atividade.
- Para nomes de coluna contendo caracteres especiais: Confirme que Use quote for Snowflake identifiers está ativado na conexão (ativado por padrão).

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

Sintoma: A implantação de um projeto que inclui uma conexão SOAP, ou uma atividade SOAP Request ou SOAP Response da API falha com:
```
Failed to deploy - Internal Error: No WSDL with locator
```
Possíveis causas:
- O WSDL foi removido, reimportado ou sua referência interna foi quebrada, portanto o projeto referencia um identificador WSDL que não existe mais.
- O projeto foi implantado ou transferido para outro ambiente antes do lançamento do Harmony 12.9, quando a implantação de um projeto podia deletar arquivos WSDL ainda em uso. O lançamento 12.9 previne a exclusão, mas um WSDL deletado antes disso ainda deve ser re-enviado.
Resolução:
1. Re-envie o WSDL para o componente afetado:
  - Para uma conexão SOAP, abra a conexão e selecione Upload URL ou Upload file (não Select existing), re-envie o WSDL, revise as configurações de Port e Select methods e clique em Save Changes.
  - Para uma atividade SOAP Request ou SOAP Response da API, abra a atividade e re-envie o WSDL na etapa 1 de sua configuração.
2. Revise todas as transformações que herdam esquemas do WSDL re-enviado e regenere-as se necessário.
3. Reimplante o projeto.
4. Se o projeto tiver múltiplos WSDLs e não estiver claro qual está afetado, consulte Solução de problemas de conexão SOAP para identificá-lo a partir de uma exportação JSON.

SOAP WSDL: schemaLocation deve usar referências relativas

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

Conector SOAP reescreve prefixos e estrutura de namespace XML

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

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

Sintoma: O conector SOAP não suporta mensagens SOAP MTOM/XOP (Message Transmission Optimization Mechanism).
Resolução: Use a solução alternativa em Suportar mensagens SOAP MTOM/XOP usando Jitterbit Studio, que constrói a solicitação MTOM fora do conector SOAP.

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

Sintoma: Um teste de conexão VTEX falha com um erro de permissão no Studio, mesmo que as mesmas credenciais funcionem em ferramentas externas como Postman.
```
You don't have permission to access this resource
```
Possível causa: A chave de usuário ou aplicação VTEX associada à conexão não possui uma ou mais permissões que o conector usa para validar a conexão. Essas permissões são mais rigorosas do que as necessárias para acesso básico a dados.
Resolução:
1. No portal de administração VTEX, abra o perfil de acesso atribuído ao usuário ou chave de aplicação que o Jitterbit está usando.
2. Confirme que o perfil de acesso inclui o recurso License Manager com acesso ao recurso Get account by identifier.
3. Salve o perfil e teste novamente a conexão VTEX no Studio.

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

Sintoma: Operações usando o conector Workday configurado com versão WSDL 42.0 ou 42.1 falham ao acessar os serviços web Human_Resources ou Resource_Management.
Possível causa: WSDL v42.0 é conhecido por retornar erros para os serviços Human_Resources (v42.0) e Resource_Management (v42.0). WSDL v42.1 é conhecido por retornar erros para o serviço Human_Resources (v42.1). Esses são problemas conhecidos específicos dessas versões de WSDL.
Resolução:
1. Na configuração de conexão do Workday, altere a versão WSDL para 41.x ou 43.0 ou posterior para operações que usam os serviços Human_Resources ou Resource_Management.
2. Teste a conexão e execute novamente as operações afetadas para confirmar que o problema foi resolvido.

Workday: Teste de conexão falha com "A tarefa enviada não está autorizada"

Sintoma: Um teste de conexão do Workday falha com:
```
Error occurred while opening connection. The Exception is Processing error occurred. The task submitted is not authorized.
```
Este erro pode ocorrer com os tipos de autenticação Basic Auth e JWT Bearer. Observe que as operações podem ser executadas com sucesso em tempo de execução mesmo quando o teste de conexão retorna este erro, porque o teste chama um serviço específico do Workday (Get_Message_Template_Translation_Request) que requer uma permissão que o ISU pode não ter, enquanto as operações de integração reais chamam serviços diferentes.
Possíveis causas:
- O Integration System User (ISU) não foi atribuído ao grupo de segurança Setup Administrator no Workday. A chamada de teste de conexão do conector é rejeitada se o ISU não tiver essa associação de grupo de segurança.
- O campo Workday Host contém um valor incorreto. Um host incorreto causa falha na conexão antes da tentativa de autenticação.
Resolução:
1. Verifique se o valor de Workday Host na configuração de conexão está correto. O host deve ser a URL base do seu tenant do Workday (por exemplo, https://wd5-impl-services1.workday.com/). Você pode confirmar o valor correto na página View API Client do Workday.
2. Na instância do Workday, abra a tarefa Assign Users to User-based Security Group, selecione Setup Administrator e confirme se o ISU está listado em System Users. Se não estiver, adicione o ISU. Para obter as etapas completas, consulte Pré-requisitos.
3. Confirme que a tarefa Configure Web Service Security também foi concluída para o ISU, conforme descrito na página Pré-requisitos.
4. Teste novamente a conexão.

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, o 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 Write do Variable.
  - Na segunda operação, leia de uma atividade Read do Variable 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 de chunking, consulte Configure operation chunking.

Agent offline ou inacessível

Sintoma: A aba Private da página Agents do Management Console mostra o agente como Unknown ou Stopped, ou o Studio exibe um erro Agent Not Running or Unreachable.
Possíveis causas:
- Os serviços Jitterbit não estão em execução.
- Os serviços estão em execução, mas o host do agente não consegue alcançar a nuvem Harmony.
- Um proxy corporativo está impedindo o agente de se conectar.
Resolução:
- Se os serviços Jitterbit não estão em execução, inicie-os:
  - Windows: Consulte Iniciar um agente Windows.
  - Linux: Consulte Iniciar um agente Linux.
  Se o serviço falhar ao iniciar, verifique o seguinte para mensagens de erro:
  - Windows: C:\Program Files (x86)\Jitterbit Agent\log e o log Event Viewer Application do Windows.
  - Linux: /opt/jitterbit/log.
  A conta que executa os serviços Jitterbit requer direitos de administrador local no Windows e acesso total ao diretório de instalação do Jitterbit.
- Se os serviços estão em execução, mas não conseguem alcançar a nuvem Harmony, verifique o seguinte:
  - A conectividade com a Internet do host do agente está funcionando.
  - O log do agente (jitterbit-agent.log) não contém mensagens de erro sobre conectividade com a nuvem.
  - O agente consegue alcançar o portal Harmony na porta 443.
- Se o agente se conecta através de um proxy corporativo, verifique se o proxy está configurado corretamente para o agente, incluindo o domínio NTLM se o proxy usa autenticação NTLM. Consulte Servidor proxy para agentes privados Jitterbit. O log de negação do servidor proxy é útil para diagnosticar o que o proxy está bloqueando.
- Se os serviços do agente estão saudáveis no host (jitterbit status mostra todos os serviços em execução), mas o agente muda repetidamente para Unknown, ou alterna entre Running, Unknown e Stopped, a conexão ou processo do agente provavelmente está sendo interrompido entre heartbeats. Verifique as seguintes possíveis causas:
  - Um dispositivo de rede (firewall, gateway NAT ou tempo limite de inatividade de VM na nuvem) pode estar fechando a conexão de saída do agente entre heartbeats. Tente reduzir o intervalo de heartbeat do agente (agent.heart.beat.interval). Para agentes hospedados na nuvem, consulte Azure VM: Conexões perdidas e erros WebSocket/I/O, que também se aplica a outras redes restritas, como AWS.
  - O agente pode ter falhado sob pressão de memória. Verifique se há OutOfMemoryError ou arquivos de despejo de falha hs_err_pid. Consulte Espaço de heap Java: OutOfMemoryError.
  - Se os agentes foram migrados recentemente para um novo sistema operacional enquanto reutilizavam um grupo de agentes que anteriormente hospedava agentes no SO antigo, o grupo reutilizado pode ser a causa. Consulte Agente mostra Unknown ou Stopped após reutilizar um grupo de agentes entre sistemas operacionais.

Agent exibindo versões ou endereços IP diferentes

Sintoma: A aba Privado da página Agentes do Console de Gerenciamento exibe versões ou endereços IP diferentes para um agente privado, ou os valores alternam para frente e para trás após reiniciar os serviços.
Possível causa: A máquina host do agente pode ter sido duplicada no nível de infraestrutura (por exemplo, um clone de VM, imagem de disco, modelo de máquina ou snapshot criado após o agente ser instalado e registrado). O host duplicado carrega o mesmo credentials.txt do agente, portanto ambos os hosts se autenticam no Harmony como o mesmo agente e executam em paralelo, colidindo. Dois agentes não podem executar simultaneamente sob as mesmas credenciais.
Resolução:
1. Confirme se uma duplicata está em execução. Interrompa o agente no host que você pretende manter, aguarde 10 minutos e atualize a aba Privado da página Agentes do Console de Gerenciamento. Se o agente mudar de Interrompido para Em execução, outro host está se reportando sob a mesma identidade.
2. Identifique e desligue o host duplicado.
3. Se não for possível desligar a duplicata, desinstale o agente, crie um novo agente com um nome diferente e reinstale-o no host que você deseja manter.
4. Verifique se o novo agente está listado como Em execução na aba Privado da página Agentes do Console de Gerenciamento.
5. Exclua a entrada do agente antigo usando Ações > Remover.

Falha de sincronização do Agent: alterações do projeto não sendo aplicadas

Sintoma: Após implantar alterações no Studio, o agente continua executando a versão anterior do projeto, ou uma operação falha porque uma conexão recém-adicionada não é encontrada no agente.
Possíveis causas:
- A implantação usou Implantação Configurável, que implanta apenas os workflows e operações selecionados. Qualquer parte do projeto fora dessa seleção permanece em sua versão implantada anteriormente no agente.
- O componente não é usado no fluxo lógico de um workflow implantado. Componentes não utilizados não são implantados, portanto uma conexão que nenhuma operação implantada referencia não é enviada ao agente.
- Ocorreu um timeout de rede ou erro de autorização durante a sincronização.
- Espaço em disco baixo no host do agente impediu que os arquivos de projeto sincronizados fossem gravados.
Resolução:
- Implante novamente o projeto completo: no Studio, use Implantar, que implanta todas as operações do projeto, em vez de uma Implantação Configurável de apenas workflows ou operações selecionados.
- Reinicie os serviços do agente para forçar uma sincronização atualizada de todos os projetos implantados.
- Revise os logs do agente para timeouts de rede relacionados à sincronização ou erros de autorização.
- Verifique o espaço em disco disponível no host do agente. Um disco cheio ou quase cheio pode impedir que o agente grave arquivos de projeto sincronizados. Consulte Espaço em disco e acúmulo de logs.

Erro 1722 na instalação do Windows

Sintoma: A instalação do agente privado do Windows falha no meio do processo, com um destes erros do Windows Installer:
```
Error 1722. There is a problem with this Windows Installer package. A program run as part of the setup did not finish as expected. Contact your support personnel or package vendor. ...
```
```
Error 1720. There is a problem with this Windows Installer package. A script required for this install to complete could not be run.
```
Ambos os erros significam que uma etapa do instalador (uma ação personalizada, nomeada na mensagem de Erro 1722) não foi concluída. Na maioria das vezes, a etapa que falha é a configuração do PostgreSQL agrupado do instalador, caso em que o log do instalador também pode mostrar um erro de script KoGetDbService ou KoInstallPostgreSQLNew, ou [Microsoft][ODBC Driver Manager] Data source name not found and no default driver specified, e o banco de dados PostgreSQL agrupado e o serviço Windows jitterbitpostgres podem não ser totalmente criados. A mensagem pode nomear uma ação diferente, como InstallVerboseLogShipper.
Possíveis causas:
- Um Microsoft Visual C++ Redistributable ausente ou conflitante (o PostgreSQL agrupado o requer).
- Caracteres proibidos na senha do PostgreSQL.
- Em uma reinstalação, componentes PostgreSQL restantes de um agente anterior. O desinstalador do agente não remove o PostgreSQL, o usuário Windows jitterbitpostgres ou suas entradas de registro por design, e esses resíduos podem impedir que a nova configuração do PostgreSQL seja concluída (por exemplo, a conta de serviço jitterbitpostgres não pode ser recriada).
- Em uma reinstalação ou atualização, componentes restantes do verbose log shipper de um agente anterior. Como com o PostgreSQL, uma desinstalação padrão não remove o serviço verbose log shipper ou seus arquivos, e esses resíduos podem fazer com que a ação InstallVerboseLogShipper do instalador falhe.
- Em uma atualização de uma instalação avançada anterior em que o PostgreSQL foi configurado para ser executado em uma conta de serviço Windows diferente de jitterbitpostgres (por exemplo, NT AUTHORITY\NetworkService), a atualização pode falhar com o Erro 1720 em versões do agente anteriores à 12.10.
Resolução:
- Instale o Microsoft Visual C++ Redistributable de 64 bits para Visual Studio usando vc_redist.x64.exe (cobre Visual Studio 2015, 2017 e 2019) antes de instalar o agente e mantenha-o instalado, pois removê-lo durante uma limpeza também quebra a instalação.
- Se a senha do PostgreSQL contiver caracteres proibidos, altere a senha para uma válida antes de tentar novamente a instalação.
  
  Nota
  
  Em agentes privados 12.8 e posteriores, o instalador valida a senha da conta de serviço do PostgreSQL (jitterbitpostgres) em relação às restrições de caracteres no momento da entrada e solicita que você a corrija antes de o PostgreSQL ser instalado.
- Se estiver reinstalando após um agente anterior, remova completamente o PostgreSQL restante primeiro: siga Desinstalar um agente privado do Windows, depois confirme que o usuário do Windows jitterbitpostgres, o programa PostgreSQL e os diretórios de dados, e as chaves de registro do PostgreSQL foram removidos.
- Se a mensagem de Erro 1722 nomear a ação InstallVerboseLogShipper, remova o serviço de envio de log detalhado restante e seus arquivos do agente anterior, depois desinstale o agente novamente e reinstale.
- Se a instalação anterior for uma instalação avançada com PostgreSQL em execução em uma conta de serviço diferente de jitterbitpostgres, atualize para a versão 12.10 do agente ou posterior, o que resolve isso. Em uma versão anterior do agente, reconfigure o serviço PostgreSQL existente para ser executado na conta de serviço do Windows jitterbitpostgres antes de atualizar.
  
  Se a instalação ainda falhar após uma limpeza completa, entre em contato com o suporte do Jitterbit.

Serviço PostgreSQL removido após falha na atualização no Windows

Sintoma: Após uma falha na atualização de um agente privado no Windows, o serviço PostgreSQL (postgresql-x64-<VERSION>) não aparece mais nos Serviços do Windows e os serviços do agente Jitterbit falham ao iniciar devido a uma dependência ausente.
Causa: Isso ocorre com versões de agente privado anteriores a 11.59 / 12.3 quando uma senha incorreta é inserida durante a atualização e o instalador falha em reverter corretamente. Esse problema foi resolvido no agente privado 11.59 / 12.3 e posteriores, onde uma senha incorreta bloqueia a atualização no mesmo diálogo e permite reinserção ou cancelamento sem afetar a instalação existente.
Resolução:
1. Abra um prompt de comando como administrador.
2. Registre novamente o serviço PostgreSQL:
```
"C:\Program Files\PostgreSQL\<VERSION>\bin\pg_ctl.exe" register -N "postgresql-x64-<VERSION>" -D "C:\Program Files\PostgreSQL\<VERSION>\data"
```
  Substitua <VERSION> pelo número da sua versão do PostgreSQL. Para encontrá-lo, consulte Versão do PostgreSQL incluída no agente privado.
3. Inicie os serviços PostgreSQL e PgBouncer:
```
net start postgresql-x64-<VERSION>
net start JitterbitPgbouncer
```
4. Inicie todos os serviços do agente Jitterbit:
```
"C:\Program Files\Jitterbit Agent\StartServices.bat"
```
5. Quando o agente estiver em execução, redefina as senhas do administrador do PostgreSQL e da conta de serviço antes de tentar novamente a atualização.

Serviços do Agent falham ao iniciar após reiniciar o Windows seguindo uma atualização

Sintoma: Uma atualização de agente privado do Windows de um agente 11.x para um agente 12.x anterior a 12.10 é concluída com sucesso, mas os serviços do Jitterbit Agent falham ao iniciar na próxima vez que o sistema host é reiniciado.
Possível causa: A atualização deixa o serviço PostgreSQL anterior do Windows (postgresql-x64-<VERSION>, onde <VERSION> é a versão instalada pelo agente anterior) com seu tipo de inicialização ainda definido como Automático. Na reinicialização, esse serviço mais antigo inicia antes do serviço PostgreSQL instalado pela atualização e ocupa a mesma porta, impedindo que o novo serviço PostgreSQL e, portanto, o agente, iniciem.
Resolução:
- Atualize para a versão 12.10 do agente ou posterior, que remove o serviço PostgreSQL anterior durante a atualização.
- Em uma versão anterior do agente, após atualizar, abra Serviços do Windows, identifique o serviço postgresql-x64-<VERSION> mais antigo (aquele anterior à atualização) e defina seu tipo de inicialização como Manual ou Desabilitado, ou desinstale-o, antes de reiniciar o sistema host. Para verificar qual versão está atualmente incluída no agente, execute o comando em Mesma versão que a incluída.

TFA impede a instalação do agent Windows de 64 bits

Sintoma: A instalação de um agente privado Windows de 64 bits falha quando a autenticação de dois fatores (TFA) está habilitada na organização.
Resolução: Desabilite temporariamente a TFA, instale o agente e reabilite a TFA. A configuração Exigir autenticação de dois fatores (TFA) está na aba Gerenciamento de Usuários das políticas de uma organização, acessada na página Organizações do Console de Gerenciamento.

Falha na instalação do Linux sem privilégios de root

Sintoma: O instalador Linux Redhat Sem Root (x64) falha.
Resolução: Verifique o seguinte:
- O usuário sem privilégios de root possui privilégios de sudo. Um administrador do sistema deve adicionar o usuário ao grupo wheel. Para verificar a associação ao grupo atual, execute groups.
- Quando conectado como o usuário jitterbit, a variável de ambiente JITTERBIT_HOME está definida para o local de instalação:
```
echo $JITTERBIT_HOME
```
  O resultado deve ser /opt/jitterbit. Isso é definido por $HOME/.bashrc.d/jitterbit quando as instruções de instalação são seguidas. Para defini-lo manualmente, execute:
```
. /opt/jitterbit/scripts/set.env
```
- Se o instalador falhar com um erro OPENSSL_3.4.0, esse é um problema conhecido no RHEL 9.7 e posterior. Consulte A instalação do agente privado sem root do RHEL 9.7 e posterior mostra um erro de OpenSSL nos problemas conhecidos do agente privado para uma solução alternativa.

Driver JDBC: "Nenhum driver adequado encontrado"

Sintoma: Uma conexão de banco de dados falha porque o driver JDBC necessário não está instalado no agente, com um erro como No suitable driver found for jdbc:<subprotocol>://....
Causa: O Jitterbit não é fornecido com todos os drivers JDBC. O driver necessário deve ser instalado manualmente.
Resolução: Instale o driver necessário manualmente: registre-o em JdbcDrivers.conf e copie o arquivo .jar do driver para JITTERBIT_HOME/tomcat/drivers/lib/, depois reinicie o agente. Para as etapas completas, consulte Instalar um driver JDBC.

Espaço de heap Java: `OutOfMemoryError`

Sintoma: Operações que processam arquivos grandes ou executam muitas operações simultaneamente falham com:
```
java.lang.OutOfMemoryError: Java heap space
```
Causa: O tamanho máximo de heap Java (-Xmx) do agente privado é muito pequeno para a carga de trabalho (arquivos grandes ou alta concorrência de jobs).
Resolução:
1. Aumentar o heap Java máximo do agente privado. Consulte Memória de heap do Tomcat para saber como alterar o valor -Xmx (por exemplo, de -Xmx1024m para -Xmx4096m).
2. Reiniciar os serviços do agente após fazer a alteração.
3. Para operações que processam arquivos grandes, configurar chunking para reduzir o uso de memória por job. O Studio aplica transformações de streaming automaticamente quando se qualificam.
4. Se a observabilidade nativa estiver ativada, usar o gráfico System Resource Capability na aba Métricas da página Agentes do Console de Gerenciamento para monitorar o uso de memória ao longo do tempo e dimensionar adequadamente o heap para a carga de trabalho.

Espaço em disco e acúmulo de logs

Sintoma: O host do agente privado fica sem espaço em disco, o que pode fazer o PostgreSQL desligar ou operações falharem com erros de permissões. Arquivos de log e temporários acumulam nos diretórios do agente, especialmente em agentes que processam altos volumes.
Resolução:
- Verificar o espaço em disco disponível no host do agente.
- Identificar arquivos grandes. Os logs do agente e arquivos temporários estão em JITTERBIT_HOME/log, JITTERBIT_HOME/tomcat/logs (catalina.out) e JITTERBIT_HOME/DataInterchange/Temp. Consulte Arquivos de log para a lista completa. Um único arquivo de log pode crescer para muitos gigabytes quando um componente registra excessivamente (por exemplo, um conector verboso inundando catalina.out) ou quando um erro se repete (por exemplo, uma conexão de banco de dados com falha se repetindo em ProcessEngine.log). Limpar arquivos superdimensionados se o espaço estiver criticamente baixo; limpar o arquivo e reiniciar o agente também pode parar o erro subjacente.
- Confirmar que o serviço de limpeza está em execução e sua retenção é respeitada. Na seção [FileCleanup] de jitterbit.conf, verificar se AutoStart é true e revisar FrequencyInHours. A retenção por diretório é definida em CleanupRules.xml usando NumDays ou NumOfHours.
- Se o serviço de limpeza não conseguir excluir arquivos de log ativos (o Tomcat mantém seus logs stdout e stderr abertos no Windows), aumentar o FileAge para esse diretório em CleanupRules.xml para pelo menos um dia, de modo que a limpeza não tenha como alvo arquivos que ainda estão sendo gravados.
- Se arquivos .dmp de despejo de falha grandes estão consumindo o disco, consulte Arquivos de mini-dump da JVM preenchem o disco do agente.

Falhas de conexão `TranDb`

Sintoma: Operações falham com erros referenciando o banco de dados PostgreSQL interno do agente privado, ou serviços internos do agente falham ao iniciar porque seu limite de conexão foi atingido. Falhas repetidas também podem preencher ProcessEngine.log, aumentando-o para muitos GB:
```
Failed to connect to back-end database 'TranDb'
```
```
FATAL: query_wait_timeout
```
```
FATAL: remaining connection slots are reserved for non-replication superuser connections
```
Possíveis causas:
- O limite max_connections do PostgreSQL interno ou o limite max_db_connections do PgBouncer é muito baixo para a carga de trabalho do agente.
- Operações estão se acumulando sob carga pesada ou uma desaceleração de rede ou endpoint, mantendo conexões de banco de dados até que o pool do PgBouncer seja esgotado (query_wait_timeout).
- Em um agente Windows, o IP Helper está interferindo nas conexões de banco de dados local do agente.
Resolução:
- Versões recentes do agent incluem limites de conexão PostgreSQL e PgBouncer mais altos por padrão, então primeiro confirme que o agent está em uma versão atual. Se um agent atual ainda esgotar seu limite de conexão, entre em contato com o suporte Jitterbit para aumentá-lo sob orientação de suporte. As instâncias PostgreSQL e PgBouncer agrupadas devem ser alteradas apenas sob orientação de suporte.
- Se os limites já forem adequados, investigue o que está mantendo as conexões abertas: revise a carga do host do agent e qualquer lentidão de rede ou endpoint upstream que esteja acumulando operações.
- Em um agent Windows, desabilite o IP Helper. Consulte Problema IPv6 no Windows.

PostgreSQL: encerramento rápido administrativo

Sintoma: todas as operações falham porque o banco de dados do agent está indisponível (as operações podem ficar travadas em um status Pendente), e o log do PostgreSQL registra um encerramento rápido:
```
received fast shutdown request
```
As operações de conexão também podem relatar FATAL: terminating connection due to administrator command.
Possíveis causas:
- Uma ação externa ou do sistema parou ou reiniciou o PostgreSQL: uma reinicialização do SO, uma atualização do Windows ou tarefa agendada, ou uma ferramenta de monitoramento ou backup que reinicia serviços.
- O host do agent ficou com pouca CPU ou memória, causando a falha do Tomcat e levando o PostgreSQL com ele.
Resolução:
- Reinicie os serviços PostgreSQL e Jitterbit agent (ou reinicie o host do agent) para recuperar. Se as operações permanecerem travadas em um status Pendente ou Em execução após o PostgreSQL voltar, entre em contato com o suporte Jitterbit, pois o pool de conexão do banco de dados do agent pode não ter se recuperado.
- Identifique o que parou o PostgreSQL: verifique o log de eventos do SO (no Windows, Visualizador de Eventos) no momento da falha para reinicializações, atualizações, tarefas agendadas, falhas de serviço ou ferramentas de backup e monitoramento que reiniciam serviços. Evite ou reagende o que está parando, e defina o serviço PostgreSQL para reiniciar automaticamente em caso de falha.
- Verifique a CPU e a memória do host do agent. Se os serviços Jitterbit estão falhando sob carga, consulte Loop de reinicialização do serviço do agent e Espaço de heap Java: OutOfMemoryError.

Falha no handshake de certificado (TLS)

Sintoma: Operações que se conectam a endpoints seguros falham durante o handshake TLS, com erros como:

error:0A000152:SSL routines::unsafe legacy renegotiation disabled

SSLHandshakeException: Received fatal alert: protocol_version

PKIX path building failed: unable to find valid certification path to requested target

Possíveis causas:
- O endpoint usa renegociação TLS legada, que o agente bloqueia por padrão.
- O agente e o endpoint não conseguem negociar uma versão TLS ou cifra comum. Os agentes da versão 11.x e 12.x usam bibliotecas de segurança diferentes, portanto um endpoint que falha ao conectar em um agente 11.x pode ter sucesso em um agente 12.x.
- O certificado do endpoint (ou um de seus intermediários) não é confiável pelo agente porque sua CA emissora não está no armazenamento de confiança cacerts do JRE do agente.
Resolução: No host do agente, execute o seguinte para confirmar qual versão TLS o endpoint negocia e se o handshake é bem-sucedido no nível de rede:
```
openssl s_client -connect hostname:port
```
Em seguida, aplique a correção que corresponde ao erro:
- Se o erro for unsafe legacy renegotiation disabled, defina AllowUnsafeLegacyRenegotiation=true na seção [Settings] de jitterbit.conf e reinicie o agente. Esta configuração requer agente versão 11.39 ou posterior.
- Se o erro for PKIX path building failed: unable to find valid certification path to requested target, o certificado do endpoint (ou um de seus intermediários) não está no armazenamento de confiança cacerts do JRE do agente. Use keytool -import no cacerts do JRE do agente (senha padrão changeit) para importar o(s) certificado(s) ausente(s), depois reinicie os serviços do agente. Para um banco de dados SQL Server acessado através de uma conexão Database, você também pode resolver isso nas configurações do driver da conexão em vez do armazenamento de confiança, tanto em agentes na nuvem quanto privados. Consulte SQL Server: Conexão falha com erro de caminho de certificado PKIX.
- Se uma falha de negociação TLS ou handshake persistir, particularmente em um agente 11.x, atualize para um agente 12.x atual, que inclui bibliotecas de segurança atualizadas e um armazenamento de confiança de certificado atualizado.

FTP: tempo limite da conexão de dados

Sintoma: O login FTP é bem-sucedido, mas a listagem de arquivos ou transferência de arquivos trava e atinge o tempo limite.
Possíveis causas:
- O modo de conexão FTP (ativo vs. passivo) é incompatível com a configuração de rede ou firewall.
- O intervalo de portas passivas definido no servidor FTP não está aberto no firewall corporativo.
Resolução:
- Nas configurações de conexão FTP, alterne a caixa de seleção Modo Passivo. O modo passivo é geralmente preferido para agentes atrás de um firewall.
- Confirme com sua equipe de rede que o intervalo de portas passivas configurado no servidor FTP está aberto no firewall entre o agente e o servidor FTP.
- Para capturar logs detalhados no nível de conexão, ative o log de depuração curl definindo CurlDebugDir na seção [Settings] de jitterbit.conf. Consulte Logs do Curl.

Problema de IPv6 no Windows

Sintoma: Alguns agentes enfrentam problemas de conectividade quando o IPv6 está ativado no host Windows. Isso pode se manifestar, por exemplo, como operações presas em estado Pendente com um ProcessEngine.log crescendo rapidamente, quando o serviço IP Helper falha e o agente perde sua conexão com o banco de dados interno.
Resolução: Desative IPv6 e IP Helper no host Windows.

Desative o IPv6 da seguinte forma:
1. Abra Painel de Controle > Rede e Internet > Conexões de Rede.
2. Abra as Propriedades da conexão de rede.
3. Desmarque a caixa de seleção para Protocolo de Internet Versão 6 (TCP/IPv6):
Desative o IP Helper da seguinte forma:
1. Abra Serviços.
2. Localize IP Helper, clique com o botão direito e selecione Propriedades.
3. Clique em Parar e defina Tipo de inicialização como Desativado:

attachment

VM do Azure: perda de conexões e erros de WebSocket/I/O

Sintoma: agents privados instalados em VMs do Azure experimentam quedas de conexão ou erros de WebSocket/I/O.
Resolução: reduza o intervalo de heartbeat do agent e aumente os tempos limite de ociosidade e fluxo da VM do Azure. Consulte VM do Azure: perda de conexões e erros de WebSocket/I/O no guia de solução de problemas do agent para obter as etapas completas.

Apache: `ConfigArgs` não instalado

Sintoma: O agente retorna:

No Installed ConfigArgs for the Service "Jitterbit Apache Server"

Causa: A conta que executa o servidor Apache Jitterbit não tem acesso total ao diretório de instalação do Jitterbit.
Resolução: Conceda à conta de serviço acesso total à pasta de instalação do Jitterbit e reinicie os serviços.

Apache/Tomcat: `APPARENT DEADLOCK`

Sintoma: Sob carga sustentada, o agente para de processar operações e pode aparecer como parando no Console de Gerenciamento. O log do agente contém:
```
ThreadPoolAsynchronousRunner: APPARENT DEADLOCK
```
O log também pode mostrar An existing connection was forcibly closed by the remote host para o banco de dados PostgreSQL do agente. Reiniciar o agente restaura a operação normal temporariamente, após o qual o deadlock recorre sob carga.
Possíveis causas:
- O pool de conexões de banco de dados do agente sofre deadlock quando o banco de dados PostgreSQL interno fica sem conexões disponíveis sob carga pesada.
- O pool de conexões de banco de dados Java do agente (mostrado como c3p0 no log) não consegue se recuperar após uma conexão de banco de dados ser brevemente perdida, por exemplo durante uma interrupção de rede transitória, mesmo que o PostgreSQL em si permaneça saudável e responsivo com timeouts padrão.
- Processos Jitterbit obsoletos estão retendo threads e conexões de banco de dados. Isso pode ocorrer quando um agente é atualizado enquanto operações ainda estão em execução, ou quando os serviços são interrompidos sem que todos os processos Jitterbit terminem corretamente.
- O host do agente está sobrecarregado pela atividade de pico, ou sua CPU está sendo limitada. Por exemplo, uma instância de nuvem expansível (como um tipo AWS t3) limita sua CPU uma vez que seus créditos de burst se esgotam, o que pode prejudicar o PostgreSQL interno sob carga.
Resolução:
- Interrompa todos os serviços do Jitterbit, finalize todos os processos do Jitterbit ainda em execução e reinicie os serviços para limpar o deadlock.
- Se o deadlock estiver no pool de conexões Java (c3p0) e o PostgreSQL em si estiver saudável, alterne o agente para seu pool de conexões C++ interno definindo UseInternalPooling=true na seção [DbInfo] de jitterbit.conf e reinicie o agente. O pool interno se recupera de conexões perdidas ou obsoletas de forma mais confiável. Em instalações novas de agentes privados do Windows versão 12.5 e posteriores, isso já está habilitado por padrão.
- Reduza a carga no agente: agende operações para evitar picos de atividade, adicione agentes ao grupo de agentes para balanceamento de carga e confirme se o host atende aos requisitos do sistema. Para hosts na nuvem, use um tipo de instância com desempenho de CPU sustentado (não expansível).
- Antes de atualizar um agente, interrompa-o com drenagem e deixe as operações em execução terminarem, para que nenhum processo fique retendo conexões de banco de dados durante a atualização. Em ambientes ocupados, reserve tempo extra para que a interrupção com drenagem seja concluída.

Apache falha inesperadamente sob carga concorrente

Sintoma: Sob carga concorrente, o processo Apache do agente falha e reinicia inesperadamente, e o agente pode aparecer brevemente como parando ou reiniciando no Console de Gerenciamento. As operações em execução no momento podem falhar ou ficar em estado incompleto.
Possíveis causas:
- Um script usa chamadas aninhadas de RunOperation para executar uma operação filha de forma síncrona (o padrão) a partir de uma operação pai, e ambas as operações leem ou escrevem a mesma variável global ao mesmo tempo.
- Uma transformação está configurada com chunking e múltiplas threads, e uma thread termina a execução antes de outra thread que começou ao mesmo tempo.
- Múltiplas operações com geração de dados de entrada e saída de componentes habilitada são executadas ao mesmo tempo.
Resolução: Atualize o agente privado para a versão 12.10 ou posterior, que resolve esses problemas. Nenhuma solução alternativa existe em versões anteriores.

Serviço de limpeza não consegue remover arquivos de log bloqueados no Windows

Sintoma: Arquivos de log em um agente privado do Windows crescem indefinidamente, e o serviço de limpeza não os remove. O log do serviço de limpeza relata um erro como:

Failed to remove file, retries (10) exhausted: '...\jitterbit tomcat server-stdout.<date>.log'. Reason: The process cannot access the file because it is being used by another process.

Possíveis causas:
- Um processo do agente está mantendo o arquivo aberto. No Windows, o serviço de limpeza não consegue remover um arquivo em uso, e o Tomcat mantém seus arquivos de log stdout e stderr abertos enquanto está em execução.
- Software de terceiros (antivírus ou um agente de monitoramento) está mantendo um bloqueio nos arquivos do diretório de log do agente.
Resolução:
- Edite CleanupRules.xml para encurtar a retenção (FileAge) dos diretórios de log afetados, para que os arquivos sejam removidos prontamente quando não estiverem mais em uso. Reinicie o agente após editar o arquivo.
- Exclua os logs stdout e stderr do Tomcat continuamente gravados das regras de limpeza, para que o serviço não tente repetidamente arquivos que permanecem bloqueados enquanto o agente está em execução.
- Se software de terceiros estiver envolvido, adicione os diretórios de instalação e log do Jitterbit à sua lista de exclusão.
- Se os logs continuarem crescendo mesmo com regras de limpeza válidas, entre em contato com o suporte do Jitterbit.

Agent falha ao reiniciar com erros de autenticação após cancelamento de registro

Sintoma: Um agente configurado com deregisterAgentOnDrainstop=true (ou a variável de ambiente AUTO_REGISTER_DEREGISTER_ON_DRAINSTOP) falha ao reiniciar após ser interrompido. Isso se aplica a agentes Docker que usam um volume persistente para /opt/jitterbit/Resources e a agentes Linux não containerizados.
Causa: Quando o agente para com deregisterAgentOnDrainstop=true, ele cancela o registro no Harmony, mas o arquivo credentials.txt agora inválido permanece no disco. Ao reiniciar, o agente tenta usar as credenciais obsoletas e falha na autenticação.

Nota

A partir da versão 12.4 do agente Docker, reiniciar o contêiner quando deregisterAgentOnDrainstop=true está ativado cancela automaticamente o registro do agente existente e registra um novo. As etapas abaixo se aplicam a agentes Docker em versões anteriores e a agentes Linux em qualquer versão.
Resolução: Remova o arquivo credentials.txt obsoleto e reinicie o agente para disparar um novo registro.

Em um agente Linux não containerizado, remova o arquivo diretamente:
```
rm /opt/jitterbit/Resources/credentials.txt
```
Em um agente Docker, remova o arquivo do volume montado:
```
docker run -i --rm -v VOLUME_NAME:/opt/jitterbit/Resources jitterbit/agent rm -i /opt/jitterbit/Resources/credentials.txt
```
Substitua VOLUME_NAME pelo nome do volume Docker sob o qual /opt/jitterbit/Resources está montado.

Alteração de log em nuvem requer reinicialização do agent privado

Sintoma: após ativar ou desativar Cloud logging para um grupo de agents privados, o comportamento do log na página Runtime do Console de Gerenciamento não muda.
Resolução: após alterar a configuração de Cloud logging na página Agents, reinicie todos os agents privados do grupo para que a alteração tenha efeito.

Adicionar um segundo agent a um grupo de agents Standard não é permitido

Sintoma: a tentativa de adicionar um segundo agent privado a um grupo existente falha, ou o grupo exibe um aviso após a adição.
Possível causa: um grupo de agents Standard permite no máximo um agent. Executar mais de um agent em um grupo requer a classe High Availability, que requer uma licença de Agent grouping for HA.
Resolução:
- Na página Agents, edite o grupo de agents e altere a Agent group class para High Availability.
- Confirme que sua organização possui uma licença de Agent grouping for HA. Os detalhes de licenciamento estão disponíveis na página Dashboard do Console de Gerenciamento.
- Se precisar adicionar uma licença, entre em contato com seu representante Jitterbit.

Falha ao adicionar um agente privado com erro de limite máximo de agentes

Sintoma: Na gaveta Detalhes do grupo de agentes de um grupo de agentes, o ícone Criar está disponível, mas salvar o novo agente privado falha com um erro de limite máximo de agentes. Dois limites separados produzem essa falha, cada um com seu próprio texto de erro.
Possíveis causas:
- O grupo de agentes está cheio. O grupo atingiu seu número máximo de agentes, que é 10 por padrão:
```
You have reached the maximum agents limit allowed for your organization. Contact your Jitterbit representative to increase the limit.
```
  Esse limite se aplica a grupos com a classe de grupo de agentes Alta Disponibilidade. Um grupo Padrão permite apenas um agente, conforme descrito em Adicionar um segundo agente a um grupo de agentes Padrão não é permitido.
- O limite de agentes privados da organização foi atingido. Todos os agentes privados permitidos pelo plano de assinatura da sua organização foram adicionados:
```
HttpErrorResponse: You've reached the maximum number of agent(s) configured for your Jitterbit organization. Please directly contact the Jitterbit Customer Success Manager assigned to you or send an email to success@jitterbit.com to review your needs and configure your organization appropriately.
```
  Esse limite se aplica independentemente de qual grupo de agentes você adiciona o agente, e um agente conta para ele assim que é adicionado, mesmo que nunca seja registrado.
Resolução:
- Para confirmar qual limite se aplica, compare a contagem de agentes do grupo de agentes com seu máximo na página Agentes e os agentes privados adicionados da sua organização com seu total licenciado na página Painel do Console de Gerenciamento.
- Se o grupo de agentes está cheio, adicione o agente a um grupo de agentes diferente ou delete um agente que não está mais em uso do grupo.
- Para aumentar qualquer um dos limites, entre em contato com seu representante Jitterbit ou Gerenciador de Sucesso do Cliente.

Agente privado não pode ser deletado

Sintoma: A tentativa de deletar um agente privado falha.
Causa: Um agente só pode ser deletado quando seu status é um de Iniciando, Parado, Não registrado ou Desconhecido. Agentes nos estados Em execução ou Parando não podem ser deletados.
Resolução:
1. Na página Agentes, verifique o status atual do agente.
2. Pare o agente e aguarde seu status mudar antes de tentar novamente a exclusão.

Grupo de agentes privados não pode ser deletado

Sintoma: A tentativa de deletar um grupo de agentes privados falha.
Causa: Um grupo de agentes privados não pode ser deletado enquanto estiver associado a um ambiente.
Resolução:
1. Na página Agentes, edite o grupo de agentes e remova todas as associações de ambiente.
2. Tente novamente a exclusão.

Desabilitar Atualização Automática de Conectores ignorado por ações de agentes

Sintoma: Conectores são atualizados em agentes privados mesmo com Desabilitar Atualização Automática de Conectores habilitado nas políticas da organização.
Causa: A política da organização Desabilitar Atualização Automática de Conectores impede que agentes privados atualizem automaticamente conectores já instalados para versões mais recentes (por exemplo, o botão Testar de uma conexão não baixa mais a versão mais recente do conector). Ela não mantém conectores em uma versão fixa em todas as situações. Conectores ainda são baixados ou atualizados, independentemente da política, quando qualquer um dos seguintes ocorre:
- Ação > Atualizar conectores é selecionado para o grupo de agentes na página Agentes do Console de Gerenciamento. Essa ação substitui explicitamente a política.
- Um agente privado é recém-instalado ou seu banco de dados PostgreSQL é redefinido (inclusive por uma atualização que atualiza o banco de dados PostgreSQL incluído, como atualizar de um agente 11.x para um agente 12.x). O agente então não tem registro armazenado de versões de conectores instaladas anteriormente, portanto baixa os conectores atuais da nuvem.
- Um agente privado é atualizado da versão 11.48 ou anterior para a versão 11.49 ou posterior, que inclui uma atualização de conector obrigatória única. Você é notificado durante a atualização que os conectores serão atualizados. Consulte as notas de atualização para Windows e Linux.
Resolução: Nenhuma ação é necessária. A política Desabilitar Atualização Automática de Conectores impede atualizações automáticas de conectores durante a operação normal, mas não se aplica às ações e eventos acima.

Agent mostra Unknown ou Stopped após reutilizar um grupo de agentes entre sistemas operacionais

Sintoma: Após migrar agentes privados para um sistema operacional diferente (por exemplo, Windows para Linux) enquanto reutiliza o mesmo grupo de agentes, os agentes migrados exibem intermitentemente como Desconhecido ou Interrompido na aba Privado da página Agentes do Console de Gerenciamento, mesmo que jitterbit status mostre os serviços em execução e as operações funcionando normalmente.
Possível causa: Reutilizar um grupo de agentes do sistema operacional anterior pode deixar metadados que interferem na geração de relatórios de status para os novos agentes. O efeito é tipicamente cosmético: serviços e operações continuam funcionando normalmente.
Resolução: Crie um novo grupo de agentes limpo para os agentes migrados em vez de reutilizar o grupo do sistema operacional anterior e registre os agentes lá.

Operações atrasadas ou enfileiradas após implantação de projeto

Sintoma: Após implantar um projeto no Studio, as operações acionadas não iniciam imediatamente, ou aparece um breve acúmulo de operações enfileiradas.
Causa: O ambiente fica bloqueado enquanto o agente sincroniza o projeto implantado. Nenhuma operação pode ser executada durante essa janela.
Resolução:
1. Para medir quanto tempo os bloqueios de sincronização duram, procure por environment-deploy em jitterbit-agent.log. Cada entrada de log inclui o ID do ambiente e a duração da sincronização em milissegundos.
2. Tempos de sincronização consistentemente longos indicam um projeto grande ou conectividade lenta com o Harmony. Para reduzir os tempos de sincronização, consulte ajuste de desempenho de sincronização do ambiente.
3. Se as durações de sincronização forem consistentemente excessivas (mais de alguns minutos), entre em contato com o suporte Jitterbit.

Agent mostrando como incapaz

Sintoma: As operações enviadas ao grupo de agentes são repetidas ou atrasadas em vez de serem executadas imediatamente. ProcessEngine.log contém mensagens repetidas como:
```
Agent (Id: ...) is incapable to process this message. Message will be auto-retried.
```
```
Capability status changed from true to false
```
Possíveis causas:
- Todos os threads de trabalho no mecanismo de processamento do agente já estão em uso, portanto o agente não pode aceitar outra operação até que um thread seja liberado. O tamanho do pool é definido por MaxNumberOfWorkerThreads na seção [ProcessEngine] de jitterbit.conf.
- Uma métrica de capacidade opcional está ativada e atingiu seu limite. O uso de CPU, uso de memória e uso de threads do Apache podem contribuir para o status de capacidade, mas todos os três estão desativados por padrão e se aplicam apenas quando ativados na seção [AgentCapability] de jitterbit.conf. O uso de memória é coletado apenas em agentes Windows, portanto não contribui para o status de capacidade em um agente Linux mesmo quando as configurações de memória estão ativadas. O Apache atende apenas solicitações de API, portanto o uso de threads do Apache é relevante apenas em um agente que manipula APIs.
- Um único agente no grupo está lidando com mais carga do que pode suportar enquanto outros agentes no grupo estão ociosos ou subutilizados.
Resolução: Revise ProcessEngine.log para longas sequências de mudanças de status de capacidade para confirmar que o agente está alternando entre estados capaz e incapaz, depois investigue o seguinte:
- Se muitas operações são executadas consistentemente ao mesmo tempo, revise MaxNumberOfWorkerThreads na seção [ProcessEngine] de jitterbit.conf. Aumentar esse valor permite mais operações simultâneas, mas também aumenta a demanda de CPU e memória, portanto defina-o de forma conservadora.
- Determine quais métricas de capacidade estão ativadas na seção [AgentCapability]. Se nenhuma estiver ativada, a carga de CPU e memória não é o que alterou o status de capacidade do agente, e a disponibilidade de threads é o gatilho mais provável. Se o uso de CPU ou memória estiver ativado, verifique-o antes das métricas de thread: qualquer um deles ultrapassando seu limite torna o agente incapaz independentemente da disponibilidade de threads. Em um agente Linux, o uso de CPU é a única métrica de recurso do sistema que se aplica.
- Verifique o uso de CPU e memória no host do agente no momento do problema. Se a observabilidade nativa estiver ativada, revise os gráficos System Resource Capability, Apache Threads e Tomcat Threads na aba Métricas da página Agentes do Console de Gerenciamento. Ao revisar gráficos de um grupo com múltiplos agentes, use valores de pico ou máximo em vez de médias, pois as médias podem mascarar um único agente sobrecarregado enquanto o resto do grupo parece saudável.
- Se o grupo de agentes contém múltiplos agentes, verifique ProcessEngine.log em todos os agentes do grupo para determinar se todos os agentes estavam incapazes simultaneamente quando a operação apresentou erro. Se apenas um agente estava incapaz, a operação deveria ter sido roteada para um agente capaz. Verifique se o balanceamento de carga está configurado corretamente para o grupo.
- Se os limites de recursos forem consistentemente atingidos, adicione agentes ao grupo para distribuir a carga.
- Se a pressão de memória for o gatilho, consulte Espaço de heap Java: OutOfMemoryError.

Transformação falha: "Failed to find file in the local file store"

Sintoma: Uma operação falha durante uma transformação com um erro indicando que um arquivo está faltando no armazenamento de arquivos local do agente:

Failed to find file in the local file store. Will attempt a re-sync the files in the environment the next time the operation runs.
There is no file in the local file store. File_ID = ...
Failed to find file in the local file store. TransformID: ..., FileID: ..., Error: There is no file in the local file store. File_ID = ... [CODE:10808]

Possível causa: Os metadados de implantação de um arquivo não sincronizaram completamente da nuvem Harmony para o agente, portanto o agente não consegue localizar o arquivo em tempo de execução. Geralmente é transitório (por exemplo, uma breve interrupção de sincronização), mas também pode ocorrer após exportar e reimportar um projeto entre ambientes.
Resolução:
1. Execute a operação novamente. Na versão 11.38 do agente e posteriores, o agente se auto-recupera dessa condição: o erro ocorre no máximo uma vez por ID de arquivo em um determinado agente, e o agente restaura os metadados ausentes na próxima sincronização de ambiente (a próxima execução de operação ou implantação). Na maioria dos casos, executar a operação novamente resolve o problema.
2. Se o mesmo arquivo continuar falhando em várias execuções em um agente atual, é provável que exista um problema mais profundo, como um ambiente que atingiu seu limite de registros de implantação ou uma regressão específica da versão. Entre em contato com o suporte Jitterbit com o nome da operação que está falhando e o TransformID e File_ID do erro.

Recuperar uma instalação do Windows com falha

Sintoma: A instalação ou atualização de um agente privado Windows falha ou deixa o agente em um estado quebrado.
Resolução: Desinstale completamente o agente e depois reinstale o software do agente.

Conector não baixado para o agent

Sintoma: Operações falham com erros indicando que um conector está indisponível ou não foi encontrado no agent, normalmente após o lançamento de uma nova versão do conector ou após implantar um projeto que usa um conector que o agent ainda não baixou:
```
This connector was not found on the Jitterbit Agent. Please be patient with us while the connector is downloaded across the agents. This may take up to several minutes
```
Possíveis causas:
- A versão do conector exigida pelo projeto ainda não foi baixada da nuvem para o agent. Geralmente é transitório e se resolve em alguns minutos.
- Para agents privados: o agent não consegue alcançar a nuvem Harmony para baixar o conector.
Resolução:
- No Studio, abra a conexão afetada e clique em Test. Isso faz com que o agent baixe a versão mais recente do conector da nuvem.
- Se o conector ainda não for baixado, verifique se a política de organização Disable Auto Connector Update está ativada. Quando ativada, o botão Test não baixa versões do conector. Consulte Agent Management.
- Para baixar o conector sem alterar a política, acesse a página Agents do Management Console, selecione o grupo de agents e escolha Action > Update connectors. Isso força uma atualização do conector no grupo e não é afetado pela política Disable Auto Connector Update.
- Para agents privados, verifique se o host do agent consegue alcançar a nuvem Harmony. Consulte Agent offline or unreachable.

Nota

Os conectores Microsoft Excel e Excel v2 falham ao carregar com esse erro especificamente na versão 12.x do agent privado. Este é um problema conhecido com uma solução alternativa separada. Consulte Excel and Excel v2 connectors fail to load nos problemas conhecidos do agent privado.

Instalação do agent não consegue se registrar através de um proxy corporativo

Sintoma: A instalação de um agent privado em um host atrás de um proxy corporativo falha durante a etapa de registro inicial, e o instalador relata que não conseguiu alcançar a nuvem Harmony:
```
Could not connect to Jitterbit Harmony cloud
```
Possíveis causas:
- O proxy está bloqueando a conexão do agent com a nuvem Harmony durante o registro.
- O proxy requer autenticação que a configuração de proxy do agent não fornece. Os agents privados suportam autenticação de proxy, incluindo um domínio NTLM. Consulte Proxy server for Jitterbit private agents.
Resolução:
1. Configure o proxy durante a configuração do agent para que o instalador consiga alcançar a nuvem Harmony através dele, fornecendo as credenciais do proxy (e domínio NTLM, se o proxy exigir). Consulte Configure a proxy during agent setup.
2. Se o registro ainda falhar através do proxy, peça ao seu time de rede para permitir os domínios e endereços IP do Jitterbit através do proxy ou contorná-lo. As URLs Harmony específicas da região estão documentadas em Allowlist information.
3. Execute o instalador novamente após o proxy estar configurado ou o host conseguir alcançar a nuvem Harmony.

Loop de reinicialização do serviço do agent

Sintoma: Os serviços do agente falham e reiniciam repetidamente. O Tomcat ou o Process Engine para e inicia em um loop sem permanecer online, e operações falham com erros como Tomcat service is not running. Se jitterbit status mostra todos os serviços saudáveis no host, mas o status exibido apenas oscila entre Running, Unknown e Stopped, trata-se de um problema de conectividade em vez de um loop de falha. Consulte Agente offline ou inacessível.
Possíveis causas:
- Um processo Jitterbit órfão de uma execução anterior (um processo Tomcat, Process Engine ou scheduler) ainda está mantendo a porta de serviço, então cada reinicialização falha com java.net.BindException: Address already in use e o agente entra em ciclo.
- O host fica sem memória e o sistema operacional encerra o processo. Isso pode acontecer quando o host tem pouca memória para a carga de trabalho, ou quando o limite de memória de um contêiner é definido muito baixo.
- O host do agente está com pouco espaço em disco, ou o banco de dados PostgreSQL interno cresceu o suficiente para falhar na inicialização.
- O Process Engine está falhando repetidamente sob carga sustentada.
Resolução:
- Confirme se trata-se de um verdadeiro loop de reinicialização. Verifique os logs do Tomcat em JITTERBIT_HOME/tomcat/logs/ e ProcessEngine.log para a exceção registrada em cada reinicialização. Uma java.net.BindException: Address already in use indica que um processo órfão está ocupando a porta.
- Interrompa o agente e finalize todos os processos Jitterbit restantes antes de reiniciá-lo. Com o agente parado, procure por processos órfãos: no Linux, execute ps aux | grep -E 'tomcat|jitterbit' e use kill em qualquer ID de processo restante; no Windows, finalize qualquer processo Jitterbit ou Tomcat restante no Gerenciador de Tarefas. Inicie o agente novamente quando nenhum permanecer.
- Verifique eventos de falta de memória. No Windows, revise os logs de Aplicativo e Sistema no Visualizador de Eventos; no Linux, execute journalctl -u jitterbit ou verifique /var/log/syslog para eventos do OOM killer. Se o host está ficando sem memória, aumente a memória disponível (ou o limite de memória do contêiner). Consulte Espaço de heap Java: OutOfMemoryError.
- Verifique o espaço em disco e o banco de dados interno. Um disco cheio ou um banco de dados PostgreSQL inchado podem causar falha nos serviços em cada reinicialização. Consulte Espaço em disco e acúmulo de logs.
- Se os logs mostrarem que o Process Engine está falhando em uma operação específica, entre em contato com o suporte Jitterbit com os detalhes da operação e os logs do agente.
- Se a observabilidade nativa estiver ativada, abra a aba Métricas da página Agentes do Console de Gerenciamento e revise os gráficos de serviço do Tomcat e Process Engine para identificar quando os serviços começaram a falhar.

Operações atingindo tempo limite ou ignorando configurações de timeout

Sintoma: Operações são executadas indefinidamente ou por mais tempo que o esperado. Para operações acionadas por API, as configurações de timeout definidas no Studio parecem não ter efeito, e as operações podem permanecer travadas em um status Em execução.
Possíveis causas:
- Por padrão, operações acionadas por APIs do API Manager ignoram as configurações de timeout de operação do Studio. A configuração EnableAPITimeout em jitterbit.conf deve ser explicitamente ativada para que operações de API respeitem os valores de timeout.
- Nenhum tempo máximo de execução de operação está definido, portanto as operações são executadas sem um limite de tempo rígido.
Resolução:
1. Para aplicar as configurações de timeout de operação para operações acionadas por API, defina EnableAPITimeout=true na seção [Settings] de jitterbit.conf.
2. Para limitar o tempo total de execução de qualquer operação, defina MaxOperationRuntimeSeconds na seção [ProcessEngine] de jitterbit.conf. Isso requer que RunOperationsInSeparateProcess seja true (o padrão).
3. Reinicie os serviços do agente após fazer alterações em jitterbit.conf.

Taxa de transferência do agent inalterada após aumentar `max.concurrent.requests`

Sintoma: Após aumentar max.concurrent.requests em jitterbit-agent-config.properties, a taxa de transferência do agente não melhora.
Possíveis causas:
- Apenas max.concurrent.requests foi alterado. A taxa de transferência do agente também depende dos pools de threads do Tomcat e Apache e dos pools de conexão HTTP, portanto aumentar apenas essa configuração sem dimensionar as outras em conjunto não produz ganho.
- O host do agente não possui CPU ou memória suficiente para a concorrência adicionada, ou o agente está entrando em um estado incapaz sob carga.
Resolução:
- Siga o procedimento completo de ajuste em vez de alterar apenas max.concurrent.requests, dimensionando as configurações de pool de threads e pool de conexão relacionadas em conjunto. Consulte Desempenho e ajuste do agente.
- Confirme que o host do agente possui CPU e memória adequados para a concorrência mais alta. Se o agente falhar ou entrar em um estado incapaz sob carga, consulte Loop de reinicialização do serviço do agente e Espaço de heap Java: OutOfMemoryError.

Desaceleração de transformação XML após atualizar para agent 11.45 ou posterior

Sintoma: Após atualizar um agente privado para a versão 11.45 ou posterior, uma transformação que itera sobre um grande array leva mais tempo para ser executada do que na versão 11.44. A desaceleração é específica para caminhos de mapeamento que usam a notação # para iterar sobre cada elemento de um grande array (aproximadamente várias centenas a alguns milhares de registros). Transformações que não iteram sobre grandes arrays não são afetadas.
Possível causa: A biblioteca de análise XML usada pelo agente foi atualizada na versão 11.45, e a versão atualizada analisa dados XML grandes mais lentamente. Isso afeta transformações que iteram sobre um grande array, porque o mapeamento atravessa repetidamente os dados analisados.
Resolução:
- Revise os caminhos de mapeamento da transformação quanto à notação #. Se um caminho usa # para iterar sobre um array, mas apenas o primeiro elemento é necessário, remova o # e reimplante. Remover # mapeia apenas o primeiro elemento, portanto aplique isso apenas quando não for necessário iterar sobre o array completo.
- Se o mapeamento precisar iterar sobre o array completo, processe menos registros por execução dividindo um grande conjunto de dados em lotes menores, para que cada transformação atravesse um array menor.

Arquivos de mini-dump da JVM preenchem o disco do agent

Sintoma: O agente gera continuamente grandes arquivos de falha da JVM (mini-dumps .dmp e .mdmp, e arquivos hs_err_pid*.log) em <JITTERBIT_HOME>/Tomcat/temp (ou, em compilações mais antigas, a pasta Tomcat diretamente), consumindo o espaço em disco do host do agente. Isso afeta agentes privados do Windows em versões anteriores à 11.49.
Possíveis causas:
- O coletor de estatísticas de disco AgentStats do agente falha na JVM ao coletar métricas de disco. Isso afeta agentes em versões anteriores à 11.49.
- Em agentes executando 11.47 ou 11.48, uma falha separada no Process Engine pode produzir os mesmos arquivos de falha.
Resolução: Atualize o agente privado para a versão 11.49 ou posterior, que resolve ambas as causas.

Se uma atualização imediata não for possível e os arquivos de falha forem provenientes da coleta de estatísticas de disco, você pode desabilitar essa coleta como uma solução alternativa (a flag DiskStatsEnabled está disponível no agente 11.44.1 e posterior):
1. Em jitterbit.conf, adicione:
```
[AgentStats]
DiskStatsEnabled=false
```
2. Reinicie os serviços do agente. Os arquivos de falha existentes podem então ser deletados com segurança para liberar espaço em disco.
3. Se você estiver na versão 11.47 ou 11.48 e os arquivos de falha continuarem, atualize para 11.49 ou entre em contato com o suporte Jitterbit para uma solução alternativa.

PostgreSQL agrupado no Linux usa MD5 em vez de SCRAM-SHA-256

Sintoma: você deseja alterar o método de autenticação PostgreSQL agrupado em um agent privado Linux de MD5 para SCRAM-SHA-256, mas o agent continua usando MD5.
Possíveis causas:
- MD5 é a criptografia de senha padrão para o PostgreSQL agrupado em agents privados Linux. SCRAM-SHA-256 era o padrão apenas nas versões 12.6 e 12.7; a versão 12.8 reverteu o padrão para MD5. Ao atualizar um agent Linux da versão 12.6 ou 12.7, o instalador solicita que você redefina a criptografia para MD5 ou mantenha SCRAM-SHA-256; consulte Atualizar um agent Linux.
- Editar apenas pg_hba.conf e postgresql.conf não completa a mudança. O PgBouncer também deve ser reconfigurado com o hash do verificador SCRAM, ou o agent falha ao iniciar.
Resolução: para alternar um agent privado Linux para SCRAM-SHA-256, siga o guia SCRAM no PostgreSQL. SCRAM-SHA-256 é um método de autenticação mais forte, enquanto MD5 oferece melhor desempenho, portanto a mudança é intencional e envolve várias etapas: o guia reconfigura o PostgreSQL agrupado, atualiza as senhas do usuário e reconfigura o PgBouncer com o novo hash. Reconfigurar a instância agrupada é a forma suportada de ativar SCRAM. Não substitua a instância agrupada pela sua própria instância PostgreSQL para obter SCRAM: agents que usam uma instância PostgreSQL diferente da agrupada não são suportados.

Conexão com sandbox do Salesforce falha com incompatibilidade de certificado

Sintoma: Uma conexão de agente privado a um endpoint que requer Server Name Indication (SNI) falha com uma incompatibilidade de certificado, enquanto a mesma conexão é bem-sucedida a partir de um grupo de agentes na nuvem ou de um teste direto com openssl ou curl no host do agente. O caso mais comum é uma URL de sandbox do Salesforce terminando em .sandbox.my.salesforce.com:
```
Certificate for <your-domain.sandbox.my.salesforce.com> doesn't match any of the subject alternative names: ...
```
Outros endpoints afetados incluem hosts que compartilham um único IP atrás de hospedagem virtual.
Causa: O handshake TLS não está incluindo a extensão SNI, portanto o servidor retorna um certificado padrão em vez daquele para o host solicitado. Para um sandbox do Salesforce, o balanceador de carga retorna o certificado de produção, cujos nomes não cobrem *.sandbox.my.salesforce.com. SNI é enviado por padrão, portanto quando está ausente, algo está suprimindo ou removendo-o.

Resolução:

Confirme que SNI é a causa. No host do agente, compare o certificado retornado com e sem SNI:

openssl s_client -connect HOST:443 -servername HOST   # certificate when SNI is sent
openssl s_client -connect HOST:443                    # certificate when SNI is omitted

Se o primeiro retorna o certificado correto e o segundo retorna o incompatível, SNI é a causa.

Verifique se SNI está explicitamente desabilitado nas opções Java do agente e remova-o se estiver. No Windows, abra o Editor do Registro em HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Apache Software Foundation\Procrun 2.0\Jitterbit Tomcat Server\Parameters\Java e edite o valor Options; no Linux, verifique JAVA_OPTS em /etc/sysconfig/jitterbit. Remova -Djsse.enableSNIExtension=false se presente (essa configuração suprime SNI). Reinicie os serviços do agente.
Se SNI ainda estiver ausente após isso, um dispositivo de rede, proxy ou pilha de rede de VM entre o agente e o endpoint está removendo-o. Sua equipe de rede deve permitir a extensão SNI.

Se a conexão também falhar de um grupo de agentes na nuvem, SNI não é a causa. O certificado do servidor pode não listar o host em seus Nomes Alternativos do Assunto. Para Salesforce, adicione a URL do MyDomain da sandbox ao certificado Salesforce ou consulte Incompatibilidade de Nome Alternativo do Assunto (SAN) do Certificado.

SSH: Conexão SFTP falha devido a caminho de arquivo de chave incorreto

Sintoma: Operações SFTP falham em um agente Windows mesmo que os arquivos de chave SSH estejam instalados corretamente.
Causa: Os valores de caminho PrivateKeyFile e PublicKeyFile na seção [SSH] de jitterbit.conf usam separadores de barra invertida do Windows (\), que não são suportados.
Resolução: Use barras normais em todos os caminhos de arquivo de chave SSH em jitterbit.conf, mesmo no Windows (por exemplo, C:/jitterbit/keys/id_rsa). Consulte [SSH].

Configurações SFTP SSH ausentes ou na seção `jitterbit.conf` errada

Sintoma: Operações SFTP que usam uma chave privada para autenticação falham com um erro de arquivo de chave privada vazio após uma atualização ou reinicialização do agente. As configurações de chave SSH adicionadas ao jitterbit.conf local também podem deixar de funcionar após o agente reiniciar.
```
CURL_DEBUG_TEXT: Using SSH private key file ''
CURL_DEBUG_TEXT: SSH public key authentication failed: Unable to extract public key from private key file
```
Possíveis causas:
- A configuração remota do agente está habilitada (está por padrão), portanto as configurações gerenciadas através da aba Configuração Jitterbit do Console de Gerenciamento têm precedência. As configurações de chave SSH adicionadas apenas ao jitterbit.conf local podem não funcionar ou podem não ser retidas após o agente reiniciar.
- As configurações de chave SSH (PrivateKeyFile, PrivateKeyPassphrase, PublicKeyFile) estão na seção incorreta. Versões mais recentes do agente analisam estritamente e ignoram configurações SSH colocadas fora da seção [SSH] (por exemplo, sob [SSL]).
Resolução:
1. Se a configuração remota estiver ativada, adicione as configurações de chave SSH lá: abra a gaveta Detalhes do grupo de agentes para o grupo de agentes, selecione a aba Configuração do Jitterbit e adicione-as na seção SSH. Consulte Configuração do Jitterbit.
2. Se o jitterbit.conf local for a fonte de configuração, confirme se as configurações de chave SSH estão colocadas em [SSH] (não em [SSL]).
3. Reinicie os serviços do agente.
4. Para solução de problemas adicional de autenticação de chave SFTP (campos de senha, frase-passe, formato de chave), consulte SFTP "Login denied. Authentication failure." ao usar chaves SSH.

Falha de autenticação SFTP em um servidor específico (incompatibilidade de cifra cURL)

Sintoma: Uma conexão SFTP usando autenticação de chave SSH falha em um agente privado com Login denied. Authentication failure., mas outras conexões SFTP do mesmo agente (usando a mesma chave) funcionam, e conectar ao servidor com falha a partir da linha de comando do SO também funciona.
```
Failed to get ftp directory list for url sftp://... Login denied. Authentication failure.
```
Causa: O servidor SFTP requer cifras SSH, troca de chaves ou algoritmos de chave de host mais recentes que a biblioteca cURL fornecida em versões mais antigas do agente não suporta. Servidores que ainda aceitam os algoritmos mais antigos continuam funcionando, razão pela qual a mesma chave funciona contra outros hosts e a partir da linha de comando do SO.
Resolução: Atualize o agente privado para a versão 11.37 ou posterior, que inclui uma biblioteca cURL atualizada com suporte para cifras SSH, troca de chaves e algoritmos de chave de host atuais.

Proxy HTTPS: Autenticação básica através do túnel proxy falha

Sintoma: Quando o agente se conecta através de um proxy HTTPS que requer autenticação básica, as conexões através do túnel proxy falham com um erro de autenticação.
Causa: Versões modernas do JDK desabilitam a autenticação básica durante o tunelamento de proxy HTTPS por padrão. A propriedade JVM jdk.http.auth.tunneling.disabledSchemes bloqueia autenticação básica a menos que seja explicitamente removida.
Resolução: Adicione -Djdk.http.auth.tunneling.disabledSchemes="" a CATALINA_OPTS antes de iniciar o Tomcat. Para instruções passo a passo para Windows, Linux e Docker, consulte Permitir autenticação básica durante tunelamento de proxy HTTPS.

Agentes privados em redes restritas: Conectividade apenas de saída

Sintoma: Ao implantar agentes privados atrás de um firewall corporativo rigoroso ou em um ambiente restrito (por exemplo, OpenShift) junto com um gateway de API privado, as equipes de rede às vezes perguntam quais portas de entrada devem ser abertas no agente para que o Harmony ou o gateway o alcancem.
Causa: Agentes privados não requerem que nenhuma porta de entrada seja aberta, devido à forma como a conectividade do agente funciona:
- Agentes privados não aceitam conexões de entrada do Harmony ou de um gateway de API privado. O agente estabelece uma conexão WebSocket de saída para o Harmony sobre HTTPS (porta 443). Todo o tráfego do Harmony e do gateway para o agente é roteado de volta por essa conexão pré-estabelecida.
- Um gateway de API privado envia solicitações de API para o Harmony, e o Harmony roteia a solicitação para o agente apropriado sobre o WebSocket de saída existente. O agente roteia a carga útil de resposta da API de volta para o gateway de API privado, portanto, o agente também deve ser capaz de alcançar o gateway (diretamente ou através de seu balanceador de carga em uma implantação com vários gateways).
Resolução:
- Abra HTTPS de saída (porta 443) do host do agente para as URLs da região Harmony. A conexão é atualizada para WSS (WebSocket seguro) para comunicação bidirecional contínua. Nenhuma porta de entrada precisa ser aberta no host do agente para Harmony ou para o gateway.
- Ao configurar o firewall, coloque na lista de permissões os serviços Jitterbit específicos da região listados em Comunicação de saída, a seção que se aplica a um agente privado atrás de um firewall.
- Se o agente foi configurado para usar portas não padrão (personalizadas), permita também essas portas através do firewall corporativo. Consulte Portas de rede.
- Se um gateway de API privado for implantado, também permita conectividade de saída de cada host do agente para o gateway (diretamente ou através de seu balanceador de carga em uma implantação com vários gateways). O agente se conecta ao gateway para retornar o payload da resposta da API. Para o fluxo de solicitação completo, consulte Arquitetura do sistema do gateway de API privado.

API personalizada retorna 504 mas o log de operação mostra sucesso

Sintoma: Uma API personalizada retorna um timeout de gateway 504, mas o log de operação na página Runtime do Console de Gerenciamento mostra que a operação foi concluída com sucesso.
Causa: Quando um payload de solicitação ou resposta (cabeçalhos mais corpo, compactado) excede aproximadamente 1 KB, o gateway de API em nuvem Jitterbit prepara o payload, e o agente privado faz uma conexão de saída para o host jitterbitsysservice de sua região para baixar o payload da solicitação (ou fazer upload do payload da resposta) antes de concluir a operação. Se o host do agente não conseguir alcançar esse host, a transferência expira e a API retorna um 504 mesmo que a operação em si tenha sido executada. A verificação de conexão do agente padrão não verifica a conectividade com o host jitterbitsysservice, portanto o agente pode parecer totalmente conectado enquanto esse host permanece bloqueado.
Resolução:
1. Adicione o host jitterbitsysservice de sua região (por exemplo, jitterbitsysservice.jitterbit.net) e seus endereços IP estáticos à lista de permissões de saída no firewall do host do agente privado. Consulte Informações de lista de permissões Jitterbit para as URLs e IPs específicos da região.
2. Verifique a conectividade executando um teste HTTP do host do agente para a URL jitterbitsysservice de sua região e confirme que a API não expira mais.

Observabilidade nativa não mostrando dados

Sintoma: Após ativar a observabilidade nativa, a aba Métricas da página Agentes do Console de Gerenciamento não mostra dados, mostra dados incompletos ou os gráficos permanecem vazios após aguardar vários minutos.
Possíveis causas:
- A seção [AgentMetrics] em jitterbit.conf não possui Enabled=true, impedindo que o serviço de métricas seja executado.
- Nem todas as configurações necessárias na seção [AgentCapability] estão definidas como true.
- Os serviços do agente não foram reiniciados após fazer alterações de configuração.
- O host do agente não consegue alcançar a nuvem Harmony, impedindo que as métricas sejam enviadas.
- Antes da versão 12.10 do agente, atualizar um agente privado do Windows cuja porta do PgBouncer já era 6434 (consulte Portas do PgBouncer) não atualizava a conexão do serviço de métricas para corresponder, então permanecia na porta antiga 6432 e a métrica do PGBouncer poderia relatar incorretamente.
- Antes da versão 12.9 do agente, instalar um agente privado como usuário não-root no Linux não provisionava o PgBouncer, então o serviço nunca iniciava e seu status sempre mostra como não íntegro.
Resolução:
- Verifique se jitterbit.conf contém todas as configurações necessárias das seções [AgentMetrics] e [AgentCapability]. Consulte o exemplo de configuração completo em configuração de observabilidade nativa.
- Verifique metrics.log e metrics_service.log no diretório de logs do agente para erros. Esses logs registram o status do serviço de métricas e indicam se as métricas estão sendo coletadas e enviadas.
- Reinicie os serviços do agente se alguma alteração de configuração foi feita.
- Verifique se o host do agente consegue alcançar a nuvem Harmony. Consulte Agente offline ou inacessível. Se o agente se conecta através de um proxy, consulte Métricas do agente ausentes quando o agente se conecta através de um proxy HTTP.
- Para um agente afetado pela incompatibilidade de porta, atualize para a versão 12.10 ou posterior do agente, que corrige automaticamente a porta de conexão do PgBouncer do serviço de métricas. Se a incompatibilidade persistir após a atualização, entre em contato com o suporte Jitterbit para verificar a porta.
- Para um novo agente privado do Linux não-root, use a versão 12.9 ou posterior, onde o PgBouncer é provisionado corretamente durante a instalação. Atualizar um agente Linux não-root existente para 12.9 ou posterior não provisiona o PgBouncer retroativamente; o agente deve ser instalado novamente.

Métricas do agent ausentes quando o agent se conecta através de um proxy HTTP

Sintoma: O agente privado se conecta ao Harmony com sucesso através de um proxy HTTP configurado, mas a aba Métricas da página Agentes do Console de Gerenciamento não mostra dados. O arquivo metrics.log pode conter entradas como Client.Timeout exceeded while awaiting headers.
Causa: O agente envia métricas por HTTPS usando uma conexão separada que não herda a configuração de proxy do agente. Se o proxy suporta apenas HTTP ou não está configurado para o tráfego de métricas do agente, as métricas não conseguem alcançar o Harmony, mesmo que o agente se conecte com sucesso.
Resolução:
1. Confirme que o proxy suporta HTTPS. As métricas do agente são enviadas por HTTPS, portanto um proxy que manipula apenas tráfego HTTP as bloqueia. Ativar HTTPS no proxy resolve o problema.
2. Se não conseguir ativar HTTPS no proxy, ou se as métricas ainda estiverem faltando após ativá-lo, o tráfego de métricas do agente precisa de sua própria configuração de proxy, separada da do agente. Entre em contato com o suporte Jitterbit para configurá-lo.

Agente Datadog falha ao iniciar após instalação do Docker

Sintoma: Após instalar o agente Datadog dentro de um contêiner Docker como parte da configuração de observabilidade Datadog, o agente Datadog falha ao iniciar.
Causa: Um problema conhecido do Datadog faz com que o agente falhe na inicialização quando o arquivo de configuração do agente de segurança não existe.
Resolução: Copie o arquivo de configuração de exemplo do agente de segurança:
```
cp /etc/datadog-agent/security-agent.yaml.example /etc/datadog-agent/security-agent.yaml
```
Em seguida, inicie o agente Datadog. Observe que no Docker, o agente Datadog não inicia automaticamente com o contêiner e deve ser iniciado manualmente após cada inicialização do contêiner:
```
sudo datadog-agent run
```

Linux: Serviços do agent falham ao iniciar após uma reinicialização ("postmaster.pid does not exist")

Sintoma: Após reinicializar um host de agent privado Linux, os serviços do agent falham ao iniciar. Executar sudo jitterbit status mostra o scheduler e outros serviços não em execução, e os logs do agent (ou console) incluem erros como:
```
postmaster.pid does not exist
```
```
reindexdb: could not connect to database template1: could not connect to server: No such file or directory
```
Causa: As permissões de arquivo no diretório de dados PostgreSQL agrupado são muito permissivas. O PostgreSQL requer que o diretório de dados seja 700 (somente do proprietário). Se as permissões forem mais amplas (por exemplo, 755 ou 777), o PostgreSQL se recusa a iniciar, o que impede que o restante do agent seja iniciado.
Resolução:
1. Confirme que /opt/jitterbit e seus subdiretórios são de propriedade do usuário e grupo jitterbit:
```
sudo chown -R jitterbit:jitterbit /opt/jitterbit
```
2. Defina o diretório de dados PostgreSQL como 700:
```
sudo chmod 700 /opt/jitterbit/DataInterchange/pgsql/data
```
3. Inicie os serviços do agent:
```
sudo /etc/init.d/jitterbit start
```

Linux: Antivírus remove PgBouncer, agent falha ao autenticar no banco de dados agrupado

Sintoma: Após migrar um agent privado Linux para um novo host (ou realizar uma instalação limpa), os serviços do agent falham ao iniciar. O postgresql.log mostra:
```
[FATAL] password authentication failed for user "jitterbit"
```
O log do agent mostra que não consegue se conectar ao banco de dados. A falha persiste em desinstalação e reinstalação completas.
Causa: Um produto antivírus baseado em host ou proteção de endpoint detecta o binário PgBouncer agrupado como suspeito e o remove ou coloca em quarentena. Sem o PgBouncer, o agent não consegue se autenticar no seu banco de dados PostgreSQL interno.
Resolução:
1. Desative temporariamente o antivírus ou produto de proteção de endpoint no host do agent.
2. Adicione o diretório de instalação do Jitterbit (normalmente /opt/jitterbit) à lista de exclusão do antivírus.
3. Reinstale o agent. No RHEL/CentOS:
```
sudo dnf reinstall jitterbit-agent
```
4. Inicie os serviços do agent e confirme a operação normal, depois reative o antivírus com a exclusão em vigor.

Verificações de segurança sinalizam `log4j-over-slf4j.jar` como vulnerabilidade do Log4j 1.x

Sintoma: Uma verificação de segurança de uma instalação de agent privado sinaliza arquivos como log4j-over-slf4j-1.7.21.jar como uma vulnerabilidade Log4j 1.x fora de suporte.
Resolução: Nenhuma ação é necessária. log4j-over-slf4j.jar não é Log4j 1.x. Faz parte da estrutura de logging SLF4J e atua como uma ponte que redireciona chamadas de bibliotecas de terceiros escritas contra a API Log4j 1.x para a estrutura de logging atual e suportada do agent. O arquivo não contém o código vulnerável Log4j 1.x. Sua presença é a mitigação do agent contra exposição Log4j 1.x, não uma instância da vulnerabilidade.

Serviço de escuta "Cluster não atingiu o tamanho mínimo necessário"

Sintoma: Operações que usam o Serviço de escuta falham com:

Failed to enable events for operation. Cluster has not met the minimum required size.

Possíveis causas:
- Poucos agentes do grupo de agentes estão em execução e ingressados no cluster. Para um grupo de $N$ agentes, contados independentemente de cada agente estar em execução, $(N / 2) + 1$ agentes (arredondados para baixo) devem estar em execução e fazer parte do cluster.
- Um ou mais agentes perderam a conexão com o cluster e não conseguiram reingressar, reduzindo o número de agentes em execução e ingressados abaixo do necessário $(N / 2) + 1$.
- Uma interrupção de rede dividiu o grupo de agentes em vários clusters menores. Por exemplo, em um grupo de 4 agentes, uma divisão de rede pode produzir dois clusters de 2 agentes cada; nenhum atende ao necessário $(N / 2) + 1$ de 3, portanto ambos relatam o erro mesmo que cada agente esteja em execução.
Resolução:
- Confirme que $(N / 2) + 1$ dos agentes do grupo estão em execução e fazem parte do cluster, onde $N$ é o número de agentes registrados no grupo de agentes, independentemente de cada um estar em execução. Por exemplo, um grupo de 4 agentes requer 3, e um grupo de 5 agentes também requer 3. Para ver quais agentes ingressaram, use a API REST do Serviço de escuta para mostrar o status do cluster.
- Verifique se as portas TCP 5701 e 5801 estão abertas entre todos os hosts de agentes e não estão bloqueadas por regras de antivírus ou firewall.
- Se o cluster está inativo e as mensagens permanecem não processadas com persistência ativada, restaure o cluster manualmente. Consulte Restauração de cluster após falha do agente.
Nota

Um número ímpar de agentes no grupo de agentes é recomendado, mas não obrigatório. Com um número par, uma interrupção de rede pode deixar o grupo dividido em duas metades, nenhuma das quais é grande o suficiente para manter o cluster em execução.

Mensagens do serviço de escuta não entregues

Sintoma: O mecanismo de repetição do cluster descarta silenciosamente mensagens não entregues após um período configurado, causando a não execução de operações dependentes.
Resolução: Para estender a janela de retenção ou impedir a exclusão, edite JITTERBIT_HOME/Resources/jitterbit-agent-config.properties e defina agent.sdk_framework.retry.deleteRetryableMessageAfter para um valor mais alto (em minutos). Para reter todas as mensagens indefinidamente, defina o valor como -1. Reinicie o agente após fazer as alterações.

Logs de operação da API personalizada não aparecem

Sintoma: Uma operação acionada por uma API personalizada é executada sem erros, mas nenhuma entrada de log aparece no Studio ou na página Runtime do Console de Gerenciamento.
Causa: Quando uma API personalizada aciona uma operação, logs de operação são gerados apenas quando a operação não é bem-sucedida. Operações de API personalizada bem-sucedidas não produzem entrada de log por padrão.
Resolução: Para capturar logs de operações de API personalizada bem-sucedidas, ative o logging de depuração de operação para a operação. Observe que o API Manager possui sua própria visualização de logging separada para solicitações de API.

O log de depuração da operação para antes da data de término selecionada

Sintoma: O logging de depuração de operação foi ativado com uma data de término futura, mas os logs param de ser gerados antes dessa data ser atingida.
Causa: Em grupos de agentes na nuvem, a data de término da configuração de logging de depuração de operação é pouco confiável. Os logs podem parar de ser gerados antes do período de tempo configurado terminar.
Resolução: Reative o logging de depuração de operação conforme necessário.

Arquivos de log de depuração da operação sem dados `.input` ou `.output`

Sintoma: Em um agente privado, uma operação possui logging de depuração de operação ativado com dados de entrada e saída de componente ativados. A pasta de log de depuração em DataInterchange/Temp/Debug contém os arquivos .jtr para cada etapa, mas os arquivos de dados .input e .output correspondentes estão faltando.
Possíveis causas:
- O serviço de limpeza do agente está excluindo arquivos .input e .output antes que possam ser revisados.
- O agente foi reiniciado enquanto a operação ainda estava em execução, portanto, os arquivos nunca foram gravados completamente. Consulte Dados de entrada/saída de componente não gerados para esse cenário.
Resolução:
1. No host do agente, abra CleanupRules.xml no diretório de instalação do agente.
2. Localize a regra de limpeza para o diretório DataInterchange/Temp/Debug e aumente o valor <FileAge NumDays = "2"...> para uma janela de retenção mais longa (por exemplo, 7).
```
<CleanupRule>
  <DirectoryPath SearchSubDirectory = "YES" >DataInterchange/Temp/Debug</DirectoryPath>
  <Pattern>*</Pattern>
  <FileAge NumDays = "7" Comparator = "GE"/>
  <FileSize Size = "0" Comparator = "GE"/>
</CleanupRule>
```
3. Reinicie os serviços do agente.

Dados de entrada/saída do componente não gerados

Sintoma: O logging de depuração de operação está ativado com a geração de dados de entrada e saída de componente ativada, mas nenhum arquivo de dados de entrada/saída aparece para operações de agente privado.
Resolução: Verifique o log do serviço Verbose Log Shipper no agente:
```
<JITTERBIT_HOME>/VerboseLogShipper/verbose-log-shipper.out.log
```
Se o log mostrar erros, reinicie o serviço Verbose Log Shipper. No Linux, isso pode ser feito sem uma reinicialização completa do agente:
```
jitterbit stop verboselogshipper
jitterbit start verboselogshipper
```
No Windows e Linux, reiniciar todos os serviços do agente Jitterbit também reinicia o serviço Verbose Log Shipper.

Jitterbit MQ: Mensagens da fila de quórum descartadas silenciosamente após 20 tentativas de NACK

Sintoma: Mensagens em uma fila de mensagens do tipo quórum desaparecem sem um erro, mesmo que estejam sendo repetidamente refiladas por meio da atividade NACK.
Possível causa: Filas de quórum impõem um limite de entrega de 20 tentativas por mensagem. Depois que uma mensagem é negativamente confirmada 20 vezes sem uma confirmação bem-sucedida, ela é permanentemente removida da fila sem gerar um erro.
Resolução:
- Configure uma Fila de Letra Morta para capturar mensagens que excedem o limite de entrega e evitar perda de dados silenciosa.
- Se for necessário reprocessamento repetido além de 20 tentativas, use um tipo de fila Clássica em vez de Quórum ao criar a fila na página Filas de Mensagens.

Jitterbit MQ: Ambiente não habilitado para mensagens

Sintoma: Operações que usam o conector Jitterbit MQ falham ao conectar ou enviar mensagens, mesmo que a fila exista no Console de Gerenciamento.
Possível causa: Todos os ambientes são desabilitados para mensagens por padrão. Uma fila de mensagens pode ser criada em um ambiente que ainda não foi habilitado para mensagens.
Resolução:
1. No Console de Gerenciamento, acesse a página Filas de Mensagens e clique no ícone de configurações .
2. Na seção Permissão de Ambientes, habilite mensagens para o ambiente afetado e clique em Salvar.

Jitterbit MQ: Limite de mensagens excedido causa "Erro ao enviar mensagem"

Sintoma: Operações que usam o conector Jitterbit MQ falham com:
```
"statuscode":500,"Error":"Error sending message."
```
Possível causa: O número de mensagens na fila atingiu seu limite configurado. Quando o limite é excedido, o serviço rejeita novas mensagens com um erro 500.
Resolução:
- Confirme ou processe mensagens existentes na fila para trazer a contagem abaixo do limite.
- Alternativamente, na página Filas de Mensagens do Console de Gerenciamento, abra a fila afetada, expanda Opções Avançadas e aumente o valor de Limite de Mensagens.

Jitterbit MQ: Mensagens com NACK bloqueiam o progresso da fila quando refiladas

Sintoma: Ao usar uma atividade NACK com Refila de Mensagens Após NACK selecionada, as mensagens retornam ao início da fila em vez do final. Se as mensagens falharem repetidamente e forem refiladas, as mesmas mensagens com falha serão reenviadas em cada recuperação subsequente, impedindo que outras mensagens na fila sejam processadas.
Causa: O agente de mensagens subjacente coloca uma mensagem refilada no início da fila para reentrega imediata. Esse comportamento não pode ser alterado por meio do conector.
Resolução: Para evitar que mensagens com falha bloqueiem o progresso da fila, use uma das seguintes abordagens:
- Fila de Letra Morta: Configure a atividade NACK para usar Rejeitar Mensagens Após NACK e configure uma Fila de Letra Morta para capturar mensagens rejeitadas. Processe a Fila de Letra Morta separadamente, com um atraso se necessário, para tentar novamente as mensagens com falha sem bloquear a fila principal.
- Republicação manual: Configure a atividade NACK para usar Rejeitar Mensagens Após NACK e use uma atividade Enviar para republicar a mensagem na fila original. Uma mensagem republicada é colocada no final da fila, permitindo que outras mensagens sejam processadas primeiro.

Login do Design Studio: erro de certificado SSL ou filtro de proxy

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

Design Studio marcado como software malicioso no macOS Sequoia

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

Design Studio: interface desfocada ou pequena em monitores de alta densidade do Windows 10

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

Design Studio: tempo longo de carregamento de projeto ao usar proxy

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

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

Possível causa: O atraso é normalmente causado pelo Design Studio tentando buscar ícones de receitas do Citizen Integrator através de um proxy que não consegue alcançar o servidor de imagens externo.
Resolução: Para as etapas de resolução, consulte Tempos de carregamento longos ao usar um proxy.

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

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

Design Studio: transformação com script falha com erro "/PRESCRIPT/ node"

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

Não é possível encontrar o nó de destino (/PRESCRIPT/).
A estrutura pode ter sido alterada, então tente abrir a transformação 'example' e atualizar as árvores de estrutura.

Possível causa: A estrutura XML interna da transformação ficou inconsistente com o esquema de destino atual, normalmente após uma alteração de esquema.
Resolução:
1. Abra a transformação com falha no Design Studio.
2. No lado Target, clique no botão de atualização no topo da árvore de estrutura. Isso relê o esquema e reconstrói a estrutura interna da transformação.
3. Salve e implante a transformação.

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

Design Studio: download de projeto falha com erro `Invalid XML character`

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

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

ou:

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

Possível causa: Os metadados do projeto contêm um caractere de controle (como 0x05 ou 0x15) que não é válido em XML. Isso pode resultar de uma URL de endpoint corrompida ou de caracteres incomuns colados em scripts, notas ou outros campos de texto.
Resolução:
1. Abra o projeto no Design Studio (ou use um backup local recente) para inspecionar os metadados.
2. Revise URLs de endpoint, scripts e notas para caracteres invisíveis ou incomuns e remova ou substitua-os. O número de linha na mensagem de erro pode ajudar a localizar a área afetada no XML exportado.
3. Salve e implante o projeto corrigido e, em seguida, tente novamente o download do Design Studio.
4. Se o conteúdo ofensivo não puder ser identificado, entre em contato com o suporte da Jitterbit com a mensagem de erro completa e a ID do projeto para possível reparo de metadados no backend.

Design Studio: componentes do projeto ausentes após download ou importação

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

Design Studio: operações ou transformações duplicadas aparecem em um projeto baixado

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

Design Studio: importação de projeto Salesforce falha com requisito de versão incorreto

Sintoma: Importar ou abrir um projeto com um endpoint Salesforce falha com um erro como:
```
The Jitterpak requires version 12.7.0.0 or higher. The Studio is currently running version [your Design Studio version]. This means that the Jitterpak cannot be opened by this Studio.
```
Isso pode ocorrer mesmo em uma versão atual e suportada do Design Studio, porque o Design Studio nunca teve uma versão 12.x.
Possível causa: O projeto foi exportado do Design Studio 11.63 ou 11.64. Essas versões marcam um projeto contendo um endpoint Salesforce com um requisito de versão incorreto (12.7.0.0) em vez da versão mínima correta. Design Studio 11.64.1 e versões posteriores exportam o requisito de versão correto.
Resolução:
- Se o projeto foi exportado para um arquivo .jpk local:
  1. Renomeie o arquivo .jpk para .zip e extraia-o.
  2. Em environment.properties, altere o valor requires-version para corresponder à sua versão instalada do Design Studio, por exemplo: requires-version=11.63.0.0.
  3. Em jitterpak.properties, altere o valor required_version para o valor codificado correspondente. Para Design Studio 11.63.0.0, use required_version=110630000000000. Para qualquer outra versão, exporte um novo projeto vazio da sua versão instalada do Design Studio e copie os valores required_version e requires-version dos arquivos desse projeto.
  4. Comprima os arquivos extraídos novamente em um arquivo .zip, renomeie para .jpk e importe-o.
  Essas etapas corrigem apenas o arquivo .jpk que você edita. Re-exportar o projeto do Design Studio 11.63 ou 11.64 escreve o requisito de versão incorreto novamente, portanto, atualize para Design Studio 11.64.1 ou posterior para evitar isso.
- Se o erro ocorrer ao baixar ou abrir um projeto implantado na nuvem Harmony em vez de ao importar um arquivo .jpk local:
  1. Atualize para Design Studio 11.64.1 ou posterior.
  2. Entre em contato com o suporte Jitterbit para solicitar a correção de backend do requisito de versão armazenado do projeto, que não está disponível na interface do Design Studio. Solicite a correção apenas após atualizar: abrir ou re-exportar o projeto com uma versão anterior afetada depois pode escrever o requisito de versão incorreto novamente no projeto.

Design Studio: falha de SOAP não é implantada quando configurada para disparar um email diretamente

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

Design Studio: transferências de arquivo se repetem inesperadamente

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

Design Studio: modo passivo de FTP e restrições de firewall de porta alta

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

Design Studio: caminhos de pasta de sucesso e erro de FTP estão no agente, não no servidor FTP

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

Design Studio: listagem de diretório FTP não pode ser analisada

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

Design Studio: alvo FTP Use FTP Rename não é funcional com operações de arquivo SFTP

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

Design Studio: alvo FTP Auto Create Directories não é confiável

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

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

Design Studio: teste de conexão de origem HTTP falha mesmo quando o endpoint está acessível

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

Design Studio: erro de URL do data center NetSuite, use URL WSDL específica da conta

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

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

ou:

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

Possível causa: O NetSuite não aceita mais URLs WSDL genéricas (por exemplo, https://webservices.netsuite.com/...) ou URLs WSDL específicas do data center (por exemplo, https://webservices.na3.netsuite.com/...). O endpoint deve usar uma URL WSDL específica da conta.
Resolução:
1. No NetSuite, acesse Setup > Company > Company Information e abra a aba Company URLs para encontrar o domínio específico da conta.
2. Construa a URL WSDL específica da conta no formato https://<account-id>.suitetalk.api.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl.
3. Atualize o campo WSDL Download URL na configuração do endpoint NetSuite com a URL específica da conta.
4. Para instruções completas, consulte URL WSDL específica da conta NetSuite.

Design Studio: usuários NetSuite com TFA não devem usar tipo de autenticação SSO

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

Design Studio: Erro `INSUFFICIENT_PERMISSION` do NetSuite TBA em tempo de execução apesar do teste de conexão bem-sucedido

Sintoma: Um endpoint NetSuite configurado com autenticação baseada em token (TBA) testa a conexão com sucesso, mas as operações falham em tempo de execução com:
```
INSUFFICIENT_PERMISSION
```
Possível causa: A função usada para gerar os tokens de acesso TBA não possui permissões suficientes para as operações sendo executadas. O teste de conexão é bem-sucedido mesmo com uma função com permissões insuficientes, mas as verificações de permissão em tempo de execução falham.
Resolução:
1. No NetSuite, alterne para uma função de Acesso Total ou Administrador ao gerar os tokens de acesso, ou adicione as permissões necessárias à função atual.
2. Regenere os tokens de acesso usando a função atualizada e reconfigure o endpoint NetSuite.

Design Studio: Lista suspensa de pesquisa salva do NetSuite vazia quando o objeto tem mais de 1.000 pesquisas salvas

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

Design Studio: Valores NULL ou em branco do NetSuite não podem ser passados para campos personalizados

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

Design Studio: Segmentos personalizados do NetSuite não exibidos na configuração de atividade

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

Design Studio: Edições de conexão OAuth 2.0 do Salesforce não refletidas no Teste de Login do Salesforce

Sintoma: Após alterar o campo URL da Instância, ID do Cliente ou Segredo do Cliente de uma Organização Salesforce existente configurada com autenticação de cliente OAuth 2.0 de 2 pernas, clicar em Teste de Login do Salesforce pode retornar um resultado de sucesso ou falha enganoso baseado nos valores de campo anteriores em vez dos que acabaram de ser inseridos.
Possível causa: Antes do Design Studio 11.67, edições nesses campos não eram salvas de forma confiável antes da execução do teste de conexão.
Resolução: Atualize para o Design Studio 11.67 ou posterior. Se usar um agente privado, também atualize para a versão 12.11 ou posterior; grupos de agentes em nuvem recebem essa correção automaticamente.

Design Studio: IDocs do SAP não encontrados quando uma operação agendada é executada em um agente diferente

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

Design Studio: Envios em massa de IDoc do SAP podem exceder limites de conexão do endpoint de destino

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

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

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

Design Studio: Arquivos temporários de armazenamento e encaminhamento do IDoc do SAP excluídos após 24 horas

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

Design Studio: Operação BAPI do SAP bem-sucedida, mas a transação não é confirmada

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

Design Studio: Ouvinte de Eventos do SAP não detecta iDocs no Windows

Sintoma: O serviço SAP Event Listener está em execução, o sistema SAP relata IDocs de saída como enviados com sucesso, mas nenhuma operação é acionada. Os logs do agente mostram erros de conexão para o ID do programa RFC, como:
```
serverException occured on [Program ID] connection null
```
Possível causa: O arquivo de serviços do Windows no host do agente não contém uma entrada para o serviço de gateway SAP. Sem essa entrada, o listener do ID do programa RFC não consegue resolver o hostname e a porta do gateway SAP, impedindo que IDocs sejam entregues ao Design Studio.
Resolução:
1. No host Windows que executa o agente privado, abra %WINDIR%\System32\drivers\etc\services como administrador.
2. Adicione as seguintes linhas:
```
sapgw00 3300/tcp
sapgw00 3300/udp
```
3. Salve o arquivo, reinicie o serviço SAP Event Listener e o agente, e teste novamente enviando um IDoc do SAP.

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

Gerenciamento de API

Esta seção aborda problemas com a capacidade de gerenciamento de API do Harmony: criação, publicação e proteção de APIs.

Não é possível publicar uma API: Limite de API de assinatura atingido

Sintoma: A criação ou publicação de uma API falha com um erro como:

You have reached Maximum no of API Service configured for your Jitterbit organization

Causa: A organização atingiu o número máximo de URLs de API publicadas permitidas pela sua assinatura. Cada API personalizada publicada, serviço OData ou API proxy (e cada um de seus clones publicados) usa uma URL de API; APIs em rascunho não contam.
Resolução: Na página APIs do API Manager, verifique as contagens de URLs de API personalizada usadas e URLs de API proxy usadas, exibidas na parte superior da página, em relação aos totais permitidos pela sua assinatura. Cancele a publicação ou exclua APIs que não são mais necessárias para liberar URLs de API (APIs em rascunho não contam contra o limite). Para aumentar o limite, entre em contato com seu Gerenciador de Sucesso do Cliente.

API publicada retorna 404 Não Encontrado

Sintoma: Chamar uma API publicada retorna um erro 404.
Possíveis causas:
- O limite de Acessos por minuto no perfil de segurança atribuído está definido como zero, bloqueando todas as solicitações. Uma alteração no nível de assinatura da organização pode redefinir esse limite, portanto, uma API que funcionava anteriormente pode começar a retornar 404s.
- A configuração, URL base ou configurações de visibilidade da API estão incorretas.
- Um gateway de API privada não está reconhecendo a API após a implantação.
- A API não foi totalmente publicada ou seus metadados estão incompletos.
Resolução:
- Abra o perfil de segurança atribuído à API e confirme se o valor de Acessos por minuto está definido como um número diferente de zero. Se o limite foi redefinido recentemente (por exemplo, após uma alteração de assinatura), restaure-o para o valor pretendido.
- Na página APIs, verifique se a API foi publicada com sucesso e se sua URL e configurações de visibilidade estão corretas.
- Se a API é servida através de um gateway de API privada, verifique a instalação do gateway e a conectividade para qualquer erro ou configuração incorreta.

HTTP 504 Gateway Timeout

Sintoma: As chamadas de API retornam:
```
504 Gateway Timeout
```
Isso geralmente ocorre após a janela de timeout do gateway (30 a 180 segundos, dependendo da configuração de Timeout da API).
Possíveis causas:
- A URL da API está malformada ou os parâmetros de caminho não estão sendo tratados corretamente, causando falha no gateway ao rotear a requisição.
- A operação de backend ou serviço externo é muito lento para responder dentro da janela de timeout do gateway, por exemplo, devido a payloads grandes ou lógica de transformação complexa.
- A requisição não pode ser atribuída a um agente disponível, por exemplo, porque o grupo de agentes está com concorrência total ou sob carga pesada, então expira no gateway antes da operação ser executada. Um sinal deste caso é que a requisição com falha não tem entrada correspondente nos logs de operação.
Resolução:
- Verifique se a URL da API está corretamente formada. Se a API usa parâmetros de caminho, considere adicionar um script à operação que analise explicitamente a URL e capture os valores dos parâmetros.
- Se o timeout é causado por um backend lento, revise a operação e sua lógica de transformação para identificar gargalos de performance, particularmente payloads de dados grandes ou chamadas externas lentas, e reduza a etapa lenta.
- Se a operação genuinamente requer mais tempo do que a configuração atual permite, aumente o timeout na aba de configurações da API. O timeout da API (padrão 30 segundos, máximo 180 segundos) é independente do timeout de operação do Studio; o timeout de operação é usado apenas em agentes privados quando a configuração EnableAPITimeout está ativada na configuração do agente.
- Se a operação não conseguir ser concluída dentro do timeout máximo, ou uma resposta em tempo real não for necessária, redesenhe a operação da API para iniciar o trabalho de longa duração de forma assíncrona (por exemplo, chamando-a com RunOperation em modo assíncrono) para que a API possa retornar uma resposta sem aguardar sua conclusão. Consulte Gerenciar operações assíncronas.
- Para timeouts intermitentes, adicione tentativas para que uma falha transitória seja repetida: use as configurações de retry integradas da conexão HTTP v2 para chamadas de saída, ou um loop de retry RunOperation com script com atraso entre as tentativas.
- Se os timeouts se correlacionam com a carga do agente, revise a capacidade do agente: execute operações que servem APIs em agentes separados de cargas de trabalho ETL pesadas e adicione agentes ao grupo se ele estiver saturado. Consulte Otimizar e melhorar a performance dos agentes privados Jitterbit.

Portal de API não refletindo alterações do projeto

Sintoma: O Portal de API mostra nomes ou atributos de projeto desatualizados após um projeto ser renomeado ou atualizado.
Possível causa: O Portal de API não sincronizou automaticamente após a alteração do projeto.
Resolução:
1. Para atualizar todas as APIs personalizadas e proxy no ambiente, abra o Portal Manager e clique em Regenerate Docs. Para atualizar uma única API, abra sua aba Documentation na página APIs e clique em Save & Publish.
2. Verifique se as informações atualizadas estão corretamente refletidas no Portal de API.

Microsoft Entra ID OAuth: Nome do perfil de segurança não pode conter espaços

Sintoma: Chamadas à API usando um perfil de segurança OAuth 2.0 de três etapas do Microsoft Entra ID (Azure AD) falham com um erro do Microsoft indicando uma incompatibilidade de URL de resposta:
```
The reply URL specified in the request does not match the reply URLs configured for the application.
```
Possível causa: O nome do perfil de segurança contém espaços. Espaços no nome do perfil fazem com que o URI de redirecionamento OAuth seja construído incorretamente, o que não corresponde a nenhuma das URLs de resposta registradas no registro do aplicativo Azure.
Resolução:
1. Abra o perfil de segurança no API Manager e renomeie-o para remover espaços (por exemplo, altere My Profile para MyProfile ou my-profile).
2. No registro do aplicativo Azure, verifique se as URLs de resposta registradas lá correspondem ao URI de redirecionamento que o API Manager gera para o perfil renomeado.

Microsoft Entra ID OAuth de 2 pernas: erro `OAUTH_INVALID_TOKEN_CODE`

Sintoma: Chamadas à API protegidas por um perfil de segurança OAuth 2.0 de duas etapas do Microsoft Entra ID falham com:
```
Failed to validate authentication token - HttpErrorResponse: OAUTH_INVALID_TOKEN_CODE
```
Possível causa: A declaração aud no JWT emitido pelo Entra ID não corresponde ao público configurado no perfil de segurança do API Manager. Isso geralmente indica que a URI de ID do Aplicativo no registro do aplicativo do Azure está mal configurada, ou o escopo OAuth que o cliente está solicitando não corresponde à URI registrada.
Resolução:
1. No portal do Azure, abra o registro do aplicativo atribuído a este perfil de segurança e vá para Expor uma API.
2. Confirme se a URI de ID do Aplicativo está definida como uma URI válida no formato api://<Application (client) ID>.
3. No perfil de segurança, confirme se o Escopo OAuth está definido como api://<Application (client) ID>/.default.
4. Atualize o aplicativo cliente para solicitar um token usando este escopo exato.
5. Se a validação ainda falhar após o público e o escopo estarem corretos, abra o manifesto do registro do aplicativo e confirme se requestedAccessTokenVersion está definido como 2. Um valor ausente ou diferente também pode causar falha na validação do token.

Azure AD Graph API foi descontinuada

Sintoma: Chamadas de API que funcionavam anteriormente com um perfil de segurança do Microsoft Entra ID (Azure AD) falham com erros de autenticação.
Possível causa: O registro do aplicativo do perfil de segurança ainda está configurado para usar a Azure AD Graph API, que a Microsoft descontinuou em 30 de junho de 2025. Registros de aplicativos que não foram migrados para o Microsoft Graph falham ao fazer solicitações.
Resolução:
1. No portal do Azure, migre o registro do aplicativo para Microsoft Graph.
2. Após a migração, atualize o manifesto do aplicativo seguindo as etapas de permissões de API na configuração do perfil de segurança OAuth de 2 pernas do Microsoft Entra ID.

Provedor de identidade Google ou Salesforce: OAuth de 2 pernas não é suportado

Sintoma: Um perfil de segurança de API configurado com Google ou Salesforce como provedor de identidade OAuth 2.0 falha quando configurado para OAuth de 2 pernas.
Possível causa: Os perfis de segurança de API OAuth 2.0 do Google e Salesforce não suportam OAuth de 2 pernas.
Resolução: Use um perfil de segurança OAuth 2.0 de 3 pernas para APIs que se autenticam com Google ou Salesforce como provedor de identidade.

Microsoft Copilot Studio: Autenticação básica não suportada

Sintoma: Conectar uma API personalizada do Jitterbit ao Microsoft Copilot Studio (como ferramenta de API REST) falha quando o perfil de segurança da API usa autenticação básica.
Possível causa: O Microsoft Copilot Studio não suporta autenticação básica. Uma API personalizada do Jitterbit cujo perfil de segurança usa autenticação básica não pode ser chamada do Copilot Studio.
Resolução:
1. No API Manager, abra o perfil de segurança atribuído à API.
2. Altere o tipo de autenticação para Chave de API ou OAuth 2.0, ou remova o perfil de segurança da API se o endpoint não exigir autenticação.
3. Republique a API e reconecte-a no Microsoft Copilot Studio. Consulte Conectar um agente de IA do Jitterbit ao Microsoft Copilot Studio.

Botão "New API" não visível apesar da função de organização correta

Sintoma: O botão New API não aparece no API Manager para um usuário que possui uma função no nível da organização, mas não é administrador da organização. Conceder a permissão Admin ao usuário no nível da organização faz o botão aparecer, mas também expõe todos os ambientes para o usuário.
Possível causa: Uma função no nível da organização sozinha não é suficiente para criar APIs. A função também deve ter acesso de Write concedido no nível do ambiente para o ambiente específico onde o usuário precisa criar APIs.
Resolução:
1. No Management Console, acesse Environments e abra o ambiente onde o usuário precisa criar APIs.
2. Para a função do usuário nesse ambiente, confirme que o acesso de Write está habilitado. Se não estiver, habilite-o e salve.
3. O botão New API agora deve estar visível para esse ambiente.

Sintoma: Uma API com dois ou mais perfis de segurança de autenticação Basic atribuídos mostra nomes de usuário inesperados nos logs da API, incluindo nomes de usuário que não pertencem a nenhum dos perfis. Algumas requisições falham com um erro 401 Unauthorized.
Possível causa: O navegador ou cliente da API (como Postman) armazenou em cache as credenciais de autenticação básica de uma sessão anterior como um cookie. Quando a API é chamada novamente, o cliente envia o cookie em cache primeiro. Se as credenciais em cache não corresponderem a nenhum dos perfis de segurança configurados, a requisição é rejeitada e o nome de usuário inesperado aparece nos logs antes da autenticação bem-sucedida com as credenciais corretas.
Resolução:
1. Limpe os cookies e o cache do navegador, ou mude para uma janela de navegação anônima ou privada, antes de testar novamente a API.
2. Confirme que o comportamento não está presente quando uma requisição nova é feita sem cookies de sessão anterior. Se o erro desaparecer, o problema é o armazenamento em cache de credenciais no lado do cliente e não um problema de configuração.
Observe que qualquer cliente HTTP que armazena cookies (incluindo ferramentas baseadas em navegador e utilitários de teste de API) pode apresentar o mesmo comportamento.

Erro `INVALID_TRIGGER_USER` ou `TRIGGER_USER_TOO_LONG`

Sintoma: Uma chamada de API usando um perfil de segurança com autenticação básica ou uma configuração de Custom Logging falha com um erro INVALID_TRIGGER_USER ou TRIGGER_USER_TOO_LONG, mesmo que as mesmas credenciais ou valor de header funcionassem anteriormente.
Possível causa: O valor usado para identificar quem chamou a requisição viola uma regra de validação: contém um caractere não permitido (INVALID_TRIGGER_USER) ou excede 256 caracteres (TRIGGER_USER_TOO_LONG).
- Para autenticação básica com a configuração padrão de Logging, esse valor é o campo User name do perfil de segurança.
- Para uma configuração de Custom Logging, é o valor que a aplicação chamadora envia no header configurado.
A validação de caracteres foi adicionada na versão 12.10 do Harmony, e o limite de comprimento foi adicionado na versão 12.11 do Harmony. Um gateway de API privado executando uma versão anterior não aplica a validação correspondente, portanto, qualquer um dos erros pode aparecer pela primeira vez após a atualização do gateway, mesmo que a configuração do perfil de segurança não tenha sido alterada.
Resolução:
- Para autenticação básica com a configuração padrão de Logging, edite o campo Nome de usuário do perfil de segurança para remover os caracteres não permitidos ou reduzi-lo para 256 caracteres ou menos, conforme aplicável, e depois atualize as credenciais em qualquer aplicação chamadora que faça referência ao nome de usuário anterior.
- Para uma configuração Personalizada de Logging, atualize a aplicação chamadora para enviar um valor de cabeçalho que não contenha caracteres não permitidos e tenha 256 caracteres ou menos.

401 Unauthorized com uma lista de permissões de IP válida (cache obsoleto)

Sintoma: Chamadas de API retornam 401 Não autorizado mesmo que o IP do cliente esteja corretamente listado nos grupos de IP confiáveis do perfil de segurança.
Possível causa: Um cache obsoleto de entradas de intervalo de IP legado no perfil de segurança está substituindo os grupos de IP confiáveis ativos.
Resolução: Migre o perfil de segurança de intervalos de IP legados para o modelo Grupos de IP Confiáveis, o mecanismo de lista de permissões atual: defina os IPs como um grupo de IP confiável e atribua-o ao perfil. Desabilitar a configuração Confiar apenas em solicitações dos seguintes intervalos de IP em um perfil que ainda usa intervalos de IP legados remove permanentemente esses intervalos (um aviso de confirmação alerta sobre isso), portanto, migre os IPs para um grupo de IP confiável em vez de desativar a configuração para limpar o cache.

Salesforce no Hyperforce: chamadas para uma API são rejeitadas após alteração dos endereços IP do Salesforce

Sintoma: Chamadas do Salesforce para uma API (mensagens de saída, chamadas Apex, Salesforce Connect ou ações invocáveis) são rejeitadas após a migração da organização Salesforce para o Hyperforce, a infraestrutura de nuvem pública do Salesforce. O perfil de segurança da API tem Confiar apenas em solicitações dos seguintes intervalos de IP habilitado com um grupo de IP confiável que lista endereços IP do Salesforce.
Possível causa: Grupos de IP confiáveis correspondem ao endereço IP de origem de uma solicitação, e os endereços que uma organização Salesforce no Hyperforce usa para chamadas de saída mudam ao longo do tempo. Um grupo que lista um conjunto fixo de endereços Salesforce deixa de corresponder.
Resolução: O Salesforce recomenda autenticar chamadas em sua rede em vez de adicionar à lista de permissões seus endereços IP de origem:
1. Abra o perfil de segurança atribuído à API e defina seu Tipo de autenticação como Chave de API. Configure a chamada do Salesforce para enviar a chave em um cabeçalho de solicitação, não em um parâmetro de consulta, para que não seja registrada em URLs de solicitação. OAuth 2.0 também está disponível, embora com o Salesforce como provedor de identidade o único fluxo seja 3-legged, que requer interação manual.
2. Após a chamada ser autenticada com sucesso, desatribua o grupo de IP confiável que lista os endereços do Salesforce, para que alterações de endereço posteriores não afetem mais a API. Desatribua o grupo em vez de desativar Confiar apenas em solicitações dos seguintes intervalos de IP, que remove permanentemente qualquer intervalo de IP legado ainda mantido no perfil.
Se sua organização exigir lista de permissões de IP, o Salesforce publica seus intervalos do Hyperforce como uma lista dinâmica em ip-ranges.salesforce.com/ip-ranges.json, anunciando adições com antecedência. Essa lista muda cada vez que o Salesforce altera seus endereços, portanto, manter uma lista de permissões atual significa rastrear o arquivo e atualizar o grupo de IP confiável para corresponder a ele. Chamadas de um endereço adicionado desde a última atualização do grupo são rejeitadas. Esses endereços também são compartilhados entre organizações Salesforce, portanto, adicioná-los à lista de permissões confirma de onde uma solicitação veio, não que veio de sua organização. Para orientação completa do Salesforce, incluindo SSL bidirecional (mTLS), Auth Providers e aplicativos conectados, consulte Manter acesso ininterrupto aos serviços Salesforce no Hyperforce.

URL de serviço excede o comprimento máximo (HTTP 414)

Sintoma: O gateway de API retorna:
```
414 URI Too Large
```
Possível causa: A URL de serviço construída (incluindo URL base, caminho de serviço e quaisquer parâmetros de caminho ou consulta) excede 8.000 caracteres.
Resolução:
- Reduza o comprimento da URL de serviço encurtando o caminho de serviço ou dividindo a API em vários endpoints.
- Para APIs proxy, confirme que a combinação da URL base e todos os caminhos de serviço definidos permaneça dentro do limite de 8.000 caracteres.

API de proxy: parâmetros de caminho de serviço exigem um documento OpenAPI

Sintoma: A configuração de um caminho de serviço de API proxy com parâmetros de caminho (por exemplo, /resource/{id}) falha quando inserida manualmente, porque o campo não aceita caracteres de chave.
Possível causa: Caminhos de serviço definidos manualmente em APIs proxy não suportam os caracteres { e } usados para definir parâmetros de caminho.
Resolução: Para usar parâmetros de caminho em um caminho de serviço de API proxy, forneça um documento OpenAPI que defina os caminhos e seus parâmetros. O API Manager descobre automaticamente os caminhos e seus parâmetros a partir da especificação OpenAPI em vez de exigir que sejam inseridos manualmente.

Não é possível excluir uma API no Gerenciador de API

Sintoma: A exclusão de uma API no API Manager falha: a interface exibe um erro genérico e a API não é removida. A falha ocorre no navegador antes de qualquer solicitação de exclusão chegar ao servidor e aparece como um TypeError de JavaScript no console do desenvolvedor do navegador.
Possível causa: A função do usuário não possui a permissão Admin. A exclusão de uma API primeiro verifica quais Grupos de API a API está associada, e visualizar a página Grupos de API requer a permissão Admin: uma função com apenas acesso de ambiente Write pode abrir a página, mas não consegue ler seu conteúdo. Quando a função não consegue ler os grupos de API, essa verificação recebe um valor que a interface não consegue processar, e a exclusão não é concluída.
Resolução: Peça a um usuário cuja função tenha a permissão de função Admin que execute a exclusão. Conceder à função afetada a permissão Admin também funciona, mas essa é uma elevação ampla no nível da organização, portanto, prefira ter um administrador existente excluir a API.

O ambiente de API não pode ser alterado após a criação

Sintoma: Uma API foi criada no ambiente errado e precisa ser movida, mas o campo de ambiente não é editável.
Possível causa: O ambiente é definido no momento da criação da API e não pode ser alterado posteriormente.
Resolução:
- Para mover uma API personalizada ou proxy para um ambiente diferente, clone a API na página APIs e selecione o ambiente correto durante a clonagem.
- Alternativamente, exporte a API de seu ambiente atual e importe-a para o ambiente de destino.

CORS ativado: solicitações `OPTIONS` são executadas sem autenticação

Sintoma: Após ativar CORS em uma API personalizada ou proxy, o método HTTP OPTIONS processa solicitações sem autenticação.
Possível causa: Ativar CORS faz com que operações que usam o método OPTIONS sejam executadas sem autenticação. Isso é necessário para suportar solicitações de preflight do navegador, mas significa que qualquer solicitação OPTIONS chega à operação sem passar pelo perfil de segurança.
Resolução:
- Se a API não usa OPTIONS para operações sensíveis, nenhuma ação é necessária. Esse é o comportamento esperado quando CORS está ativado.
- Se for necessário o tratamento autenticado de OPTIONS, desative CORS na API ou reestruture a operação para detectar e tratar explicitamente solicitações de preflight não autenticadas.

API de proxy em nuvem: a API de destino deve estar acessível publicamente

Sintoma: Uma API proxy que usa o gateway de API na nuvem hospedado pela Jitterbit retorna erros ou não consegue alcançar a API de destino.
Possível causa: Ao usar o gateway de API na nuvem, a API sendo proxiada deve estar acessível pela internet pública. APIs atrás de um firewall ou em uma rede privada não podem ser alcançadas pelo gateway na nuvem.
Resolução:
- Confirme se a API de destino está acessível pela internet pública, mesmo que esteja protegida.
- Se a API de destino precisar permanecer atrás de um firewall, implante um gateway de API privado na mesma rede privada em vez de usar o gateway de API na nuvem.
- Para adicionar os endereços IP do gateway na nuvem à lista de permissões para que o gateway possa acessar a API proxiada, consulte Informações de lista de permissões.

A configuração Mostrar Payloads de Solicitação e Resposta não tem efeito para APIs de proxy

Sintoma: O botão Mostrar Payloads de Requisição e Resposta nos Logs aparece nas configurações de uma API proxy, mas ativá-lo não tem efeito na saída de logs.
Possível causa: O registro de payload de requisição e resposta não é suportado para APIs proxy. O botão fica visível na interface de configuração, mas não funciona para este tipo de API.
Resolução: Para capturar payloads de requisição e resposta, use uma API customizada que chame o mesmo endpoint, onde a configuração Mostrar Payloads de Requisição e Resposta nos Logs é suportada.

Gateway privado retorna uma página 400 "verify Jitterbit Services" sem entrada de log de API

Sintoma: Solicitações através de um gateway de API privado falham intermitentemente com uma resposta HTTP 400. Em vez de uma resposta normal da API, o chamador recebe uma página de erro HTML semelhante a:
```
Error connecting to Jitterbit Services. Please verify that all Jitterbit Services are running on your Jitterbit Agent machine - including the Apache server and Process Engine.
```
Nenhuma entrada aparece nos logs da API para a solicitação com falha, porque a solicitação nunca chegou a uma operação.
Possível causa: O grupo de agentes privados está sobrecarregado e não possui threads de trabalho Apache disponíveis para aceitar trabalhos do gateway de API privado. Quando nenhuma thread de trabalho está livre, a transferência de gateway para agente falha com uma redefinição de conexão antes que a solicitação possa ser registrada ou executada.
Resolução:
1. Adicione mais agentes ao grupo de agentes para distribuir a carga e confirme que os hosts dos agentes possuem CPU e memória suficientes.
2. Monitore o uso de threads de trabalho Apache dos agentes. Se a observabilidade nativa estiver ativada, revise os gráficos Apache Thread Capability, Apache idle workers e Apache busy workers (consulte Dashboards) para confirmar se as threads estão sendo esgotadas durante as falhas.
3. Se os agentes consistentemente ficarem sem threads de trabalho Apache mesmo após dimensionamento, entre em contato com o suporte Jitterbit para revisar a capacidade de threads de trabalho Apache dos agentes (a configuração MaxRequestWorkers). Não altere os arquivos de configuração Apache do Jitterbit a menos que seja direcionado pelo suporte Jitterbit. Consulte Arquivos de configuração Apache.

Alterações de perfil de segurança levam vários minutos para entrar em vigor

Sintoma: Uma API continua se comportando como se uma configuração de perfil de segurança antiga estivesse ativa, mesmo após o perfil ter sido atualizado e salvo.
Possível causa: Perfis de segurança são armazenados em cache no gateway de API. Alterações em um perfil de segurança ativo não entram em vigor imediatamente.
Resolução:
1. Aguarde vários minutos após salvar uma alteração de perfil de segurança antes de testar a API afetada.
2. Se o problema persistir após 10 minutos, confirme se a alteração foi salva corretamente reabrindo o perfil de segurança.

Excluir uma API não atualiza a documentação do Portal de API

Sintoma: Após excluir uma API, sua documentação OpenAPI permanece visível no Portal de API.
Possível causa: A documentação do Portal de API não é atualizada automaticamente quando uma API é excluída do API Manager.
Resolução:
- Após excluir uma API, abra o Portal Manager e remova ou atualize manualmente a entrada de documentação da API lá.
- Alternativamente, use a aba Documentation da API antes de excluí-la para remover a entrada do Portal primeiro.

O perfil de segurança não pode ser excluído enquanto ainda estiver atribuído a uma API publicada

Sintoma: A tentativa de deletar um perfil de segurança falha ou a opção de deletar fica indisponível, mesmo após remover a atribuição do perfil de uma API.
Possível causa: Após remover um perfil de segurança da configuração de uma API, é necessário salvar e republicar a API antes que o perfil seja considerado totalmente desatribuído. Até que a API seja republicada, o API Manager ainda trata o perfil como em uso.
Resolução:
1. Após remover a atribuição do perfil de segurança da API, clique em Salvar e depois Publicar a API.
2. Após a API ser republicada com a configuração atualizada, o perfil de segurança não aparecerá mais como em uso e poderá ser deletado.

OAuth de 2 etapas volta para 3 etapas em versões de gateway privado anteriores a 10.48

Sintoma: Um perfil de segurança configurado para OAuth de 2 etapas usa OAuth de 3 etapas em vez disso quando servido através de um gateway de API privado.
Possível causa: Gateways de API privados anteriores à versão 10.48 não suportam OAuth de 2 etapas. Se a versão do gateway for anterior à 10.48, o perfil de segurança retorna para OAuth de 3 etapas mesmo quando OAuth de 2 etapas está configurado.
Resolução:
1. Verifique a versão do gateway de API privado que serve a API.
2. Atualize o gateway para a versão 10.48 ou posterior para ativar o suporte a OAuth de 2 etapas.

ALB multi-gateway: todos os contêineres devem estar no mesmo host

Sintoma: Em um ambiente multi-gateway containerizado atrás de um balanceador de carga de aplicação (ALB), as chamadas de API falham intermitentemente ou os payloads não podem ser recuperados, mesmo que os gateways individuais pareçam saudáveis.
Possível causa: Ao usar um gateway de API privado containerizado com um ALB, todos os containers do gateway devem ser executados no mesmo host. Containers implantados em hosts diferentes não conseguem coordenar a recuperação de payload, causando falhas intermitentes.
Resolução:
1. Confirme que todos os containers do gateway de API privado no grupo estão sendo executados no mesmo host físico ou virtual.
2. Se os containers estiverem distribuídos em vários hosts, consolide-os em um único host.
3. Para implantações em múltiplos hosts, revise a configuração do ALB no guia de instalação do gateway para requisitos de configuração adicionais.

Gateway privado: a configuração SSL personalizada é sobrescrita por atualizações

Sintoma: Após atualizar um gateway de API privado, as configurações personalizadas de protocolo SSL ou cipher não são mais aplicadas e o gateway reverte para o comportamento padrão de TLS.
Possível causa: O processo de atualização do gateway de API privado sobrescreve o arquivo de configuração local (/usr/local/openresty/nginx/conf/onpremise.conf). Qualquer alteração manual neste arquivo, incluindo restrições de protocolo SSL personalizado ou listas de cipher, é perdida durante a atualização.
Resolução:
1. Antes de atualizar o gateway de API privado, faça backup do arquivo de configuração local.
2. Após a conclusão da atualização, reaplique suas configurações SSL personalizadas ao novo arquivo de configuração.

Gateway privado retorna HTTP 507 ou "No such file or directory"

Sintoma: Endpoints do gateway de API privado retornam 507 Insufficient Storage. Os logs do gateway mostram:
```
could not open payload file: No such file or directory
```
mesmo quando há espaço em disco abundante nos hosts do gateway.
Possível causa: Aqui, 507 significa que o gateway não conseguiu abrir o arquivo de payload ou resposta hospedado para a solicitação; não necessariamente indica que o host está sem armazenamento. Em um gateway de API privado com múltiplos nós atrás de um balanceador de carga, isso pode ocorrer quando o nó que atende uma solicitação não consegue acessar um arquivo hospedado que outro nó criou, porque esses arquivos são locais para cada nó.
Resolução:
1. Confirme que os hosts do gateway não estão genuinamente sem armazenamento verificando o uso de disco e inode (df -h e df -i). Libere espaço e refaça o teste apenas se estiverem realmente cheios.
2. Se o gateway é executado como múltiplos nós atrás de um balanceador de carga, confirme que o balanceador roteia cada solicitação e sua resposta consistentemente para o mesmo nó, porque os arquivos de payload e resposta hospedados são locais ao nó que os criou. Para gateways em contêiner, consulte Multi-gateway ALB: All containers must be on the same host.
3. Se o erro persistir, ative o log de rastreamento no gateway (defina traceLogsEnabled como true na configuração do gateway) e entre em contato com o suporte Jitterbit com os logs de rastreamento resultantes, os logs do gateway (/opt/jitterbit/var/log/api-gateway), os logs do NGINX ou OpenResty e a saída de ls -lR para os diretórios hosted-files em cada nó. O suporte pode verificar condições do servidor que não são configuráveis pelo cliente, como o mapeamento host-para-ambiente, entradas de domínio privado obsoletas e permissões de arquivo.

A instalação ou atualização do gateway privado falha com dependências ausentes

Sintoma: Executar yum install para instalar ou atualizar um gateway de API privado Linux (RPM) para a versão 10.62 ou posterior falha com erros de dependência ausente:

Nothing provides geoip-devel needed by jitterbit-api-gateway-11.x.x-x.x86_64
Nothing provides libGeoIP.so.1()(64bit) needed by jitterbit-api-gateway-11.x.x-x.x86_64

Possível causa: O gateway de API privado versão 10.62 e posterior requerem os pacotes geoip-devel e libGeoIP, fornecidos pelo repositório EPEL. A instalação documentada ativa o EPEL antes de instalar o gateway. O erro ocorre quando essa etapa é ignorada ou quando o host do gateway não tem acesso à internet e não consegue alcançar o EPEL para baixar os pacotes.
Resolução:
- Em um host do gateway com acesso à internet, ative o repositório EPEL antes de instalar o gateway, conforme descrito em Install a private API gateway: execute yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm e, em seguida, execute novamente a instalação do gateway.
- Em um host isolado sem acesso à internet, instalar apenas o pacote epel-release adiciona apenas a definição do repositório; não baixa os pacotes geoip-devel e libGeoIP. Em uma máquina com acesso à internet, baixe esses pacotes e suas dependências transitivas, transfira-os para o host do gateway e instale-os em ordem de dependência com yum install <package.rpm> antes de executar novamente a instalação do gateway.

O autoteste do gateway privado retorna "Failure, test call to API failed"

Sintoma: O utilitário de autoteste da linha de comando do gateway de API privado retorna:
```
Failure, test call to API failed
```
Possível causa: Nas versões 11.30 e anteriores do gateway de API privado, o utilitário de autoteste cria uma API de teste que não possui campos obrigatórios (Service Name e Path), causando falha na chamada de teste.
Resolução:
- Atualize o gateway de API privado para a versão 11.31 ou posterior, que resolve isso automaticamente.
- Se não for possível atualizar imediatamente: abra a configuração da API para a API chamada ApiGatewayTest, preencha o campo Service Name com qualquer valor (por exemplo, service), defina Path como /, salve e publique, depois execute novamente o utilitário de autoteste.

OData $count ou $inlinecount retorna um erro quando nenhum registro corresponde

Sintoma: Uma consulta de serviço OData usando as opções de consulta do sistema $count ou $inlinecount retorna um erro em vez de 0 quando nenhum registro corresponde ao filtro.
Possível causa: Por padrão, um serviço OData retorna um erro em vez de 0 quando uma consulta $count ou $inlinecount não corresponde a nenhum registro.
Resolução: Em agentes privados executando a versão 11.32 ou posterior, defina o parâmetro OData $noErrorOnZeroCount como true na configuração do serviço OData. Isso faz com que consultas $count retornem 0 em vez de um erro quando nenhum registro corresponde.

API de proxy: hífens de cabeçalho de solicitação substituídos por sublinhados

Sintoma: Uma operação de API de proxy recebe cabeçalhos de solicitação com hífens substituídos por sublinhados (por exemplo, X-Custom-Header chega como X_Custom_Header), causando falha nas buscas de cabeçalho.
Possível causa: As APIs de proxy têm uma configuração disable-hyphen-replacement que controla se os hífens nos nomes dos cabeçalhos de solicitação são substituídos por sublinhados. Para novas APIs de proxy, essa configuração é padronizada como true (substituição desabilitada). APIs de proxy mais antigas podem ter a configuração como false, causando a substituição.
Resolução:
- Na configuração da API de proxy, verifique a configuração do cabeçalho disable-hyphen-replacement. Para preservar hífens nos nomes dos cabeçalhos, certifique-se de que a configuração é true.
- Se a API de proxy foi criada antes dessa configuração padrão ser introduzida e a substituição está ocorrendo inesperadamente, atualize a configuração para true e republique a API.

Os logs de operação não são visíveis para operações acionadas por API quando o modo de depuração está desativado

Sintoma: Após chamar uma API, o log da API mostra que a chamada foi executada com sucesso, mas nenhum log de operação aparece na página Runtime para a operação que a API acionou. Chamadas para WriteToOperationLog de dentro da operação também não produzem entradas de log visíveis.
Possível causa: Quando uma operação é acionada por meio de uma API publicada, as execuções bem-sucedidas não aparecem nos logs de operação por padrão. Operações malsucedidas são sempre registradas; apenas logs de operação bem-sucedidos e qualquer saída de WriteToOperationLog de execuções bem-sucedidas ficam ocultos. Execuções bem-sucedidas aparecem apenas quando Ativar modo de depuração até (uma configuração do API Manager) ou Log de depuração de operação (uma configuração do agente) está ativo.
Resolução:
1. Para ver logs de operação bem-sucedidos e saída de WriteToOperationLog, ative Ativar modo de depuração até para a API na guia de configurações da API, ou ative Log de depuração de operação no agente.
2. Para também capturar os dados brutos de solicitação e resposta e cargas úteis, ative Ativar modo de depuração até (como na etapa 1) ou combine Log de depuração de operação com Mostrar cargas úteis de solicitação e resposta em logs e Log detalhado. Quais dados cada configuração captura depende da combinação ativada; para o detalhamento completo, consulte Dados de solicitação e resposta da API.
3. Desative o modo de depuração após coletar os logs necessários, pois deixá-lo ativado aumenta o volume de logs.

Payload de API disponível no agente por 2 dias

Sintoma: Um fluxo de trabalho que recupera uma carga útil de solicitação de API do agente mais de 2 dias após a chamada da API não consegue encontrar a carga útil.
Possível causa: As cargas úteis de solicitação de API para APIs personalizadas e serviços OData são armazenadas no agente por um máximo de 2 dias. Após esse período, a carga útil fica disponível apenas se a operação já a tiver gravado em um conector de armazenamento persistente (como Armazenamento Temporário, Compartilhamento de Arquivo ou banco de dados).
Resolução:
- Projete operações que consomem cargas úteis de solicitação de API para processar os dados imediatamente quando a API é chamada, em vez de adiar a recuperação da carga útil.
- Se a carga útil precisar ser retida para processamento mais longo, grave-a em um local de armazenamento persistente na operação inicial acionada por API.

A página de Logs da API retém seleções de filtro anteriores

Sintoma: A página Logs de API não está exibindo as entradas de log esperadas, mesmo que a API esteja funcionando com sucesso.
Possível causa: A página Logs de API lembra as seleções de filtro da sessão anterior. Um filtro aplicado anteriormente pode estar ocultando os resultados esperados.
Resolução: Na página Logs de API, revise todos os filtros ativos e limpe qualquer um que possa estar excluindo as entradas esperadas.

APIs não publicadas não aparecem no dropdown de APIs do Analytics

Sintoma: Uma API não aparece no menu suspenso APIs na página Analytics, portanto, os dados de análise dessa API não podem ser filtrados.
Possível causa: Apenas as APIs atualmente publicadas aparecem no menu suspenso APIs. As APIs que foram despublicadas são excluídas do menu suspenso, mesmo que existam logs de API para essas APIs.
Resolução:
- Confirme se a API foi publicada. Para visualizar dados de análise, a API deve estar em estado publicado.
- Para visualizar entradas de log de uma API não publicada, use a página Logs de API. Os dados de log permanecem disponíveis lá, mas não podem ser filtrados por nome de API.

Erro 429: Limite mensal de chamadas da API excedido

Sintoma: Todas as APIs da organização retornam repentinamente erros HTTP 429.
Possível causa: A organização esgotou seu limite mensal de chamadas de API conforme definido por sua licença. Quando o limite é excedido, todas as chamadas de API são rejeitadas com uma resposta 429 pelo restante do mês.
Resolução:
- Verifique a contagem atual de chamadas em relação ao seu limite mensal na página APIs. O limite é redefinido no primeiro dia do mês seguinte.
- Para evitar atingir o limite, configure limites de taxa no nível do ambiente ou do perfil de segurança usando a configuração Chamadas por minuto para distribuir a carga e aplicar limites de consumo por consumidor.
- Para aumentar o limite mensal de chamadas da sua organização, entre em contato com seu Gerenciador de Sucesso do Cliente.

Erro 429: IP do consumidor não está no intervalo de IPs confiáveis

Sintoma: Um consumidor ou aplicação específica recebe erros HTTP 429 ao chamar uma API, enquanto outros consumidores conseguem chamar a mesma API com sucesso.
Possível causa: O perfil de segurança atribuído à API tem grupos de IP confiável configurados. Solicitações de endereços IP fora dos intervalos permitidos são rejeitadas com uma resposta 429.
Resolução:
1. Abra o perfil de segurança atribuído à API e revise sua configuração de grupo de IP confiável.
2. Adicione o endereço IP do consumidor ou intervalo de endereços a um grupo de IP confiável existente, ou crie um novo grupo de IP confiável que inclua os endereços necessários.

Limite de taxa no nível da plataforma: 200 requisições por minuto

Sintoma: APIs hospedadas no gateway de API em nuvem gerenciado pela Jitterbit são limitadas ou rejeitadas com uma resposta 429 Too Many Requests sob alto tráfego, mesmo quando os limites de taxa do perfil de segurança não foram atingidos.
Possível causa: O gateway de API em nuvem gerenciado pela Jitterbit aplica um limite no nível da plataforma de 200 requisições de API por minuto por organização, compartilhado entre todos os tipos de API (customizada, proxy e OData). Este limite não se aplica a gateways de API privados.
Resolução:
- Analise seus padrões de tráfego de API e distribua as chamadas ao longo do tempo, se possível, para permanecer dentro do limite de 200 requisições por minuto.
- Se seu caso de uso exigir uma taxa de transferência sustentada acima deste limite, implante um gateway de API privado onde a taxa de transferência é determinada pela capacidade do servidor host em vez de um limite no nível da plataforma.

Zscaler ou firewall com interceptação SSL bloqueia o acesso à API

Sintoma: Chamadas de API falham com erros de certificado, ou endpoints de backend não conseguem acessar APIs protegidas com TLS quando roteadas através de uma rede gerenciada por Zscaler ou similar com inspeção SSL.
Possíveis causas:
- Zscaler e proxies de segurança similares realizam inspeção SSL/TLS interceptando tráfego HTTPS e assinando-o novamente com seu próprio certificado de CA. Sistemas cliente que não confiam na CA raiz do Zscaler rejeitam a conexão.
- Importar manualmente o certificado Jitterbit no armazenamento de confiança não é uma solução confiável: quando Jitterbit renova seu certificado, a cópia importada manualmente fica desatualizada e quebra a conexão novamente.
Resolução:
- Instale o certificado de CA raiz do Zscaler no armazenamento de confiança do SO ou navegador nos sistemas que fazem as chamadas de API, para que certificados assinados novamente pelo Zscaler sejam confiáveis.
- Para ferramentas como curl, wget ou openssl, configure-as para usar o proxy HTTP definido no ambiente Zscaler.
- Solicite uma exceção de política do Zscaler para os nomes de host do gateway de API Jitterbit para contornar a inspeção SSL para esses destinos específicos.
- Analise as regras do arquivo PAC (proxy auto-configuration) da organização para confirmar que os endpoints Jitterbit são tratados corretamente.
- Não importe manualmente o certificado folha Jitterbit em um armazenamento de confiança como solução alternativa: use a CA raiz do Zscaler em vez disso para evitar problemas quando Jitterbit renova seu certificado.

EDI

Esta seção aborda problemas com a capacidade EDI do Harmony: comunicação com parceiros comerciais e processamento de documentos EDI.

Falha de conexão AS2 ou certificado

Sintoma: As transmissões AS2 de saída falham ou os reconhecimentos do parceiro comercial não são recebidos.
Possíveis causas:
- O certificado AS2 expirou ou não é mais confiável pelo parceiro comercial.
- O algoritmo do certificado não corresponde ao que o parceiro comercial exige (por exemplo, SHA-1 vs. SHA-256).
- A URL do endpoint AS2, ID do parceiro ou outros parâmetros de conexão estão incorretos.
- Um firewall ou restrição de rede está bloqueando o tráfego AS2 de saída na porta 443 ou na porta AS2 configurada.
Resolução:
- Revise as configurações de comunicação AS2 do parceiro comercial afetado e confirme que a URL do endpoint, IDs de parceiro e configurações de certificado estão corretos.
- Verifique a data de expiração do certificado e renove-o se tiver expirado. Troque o certificado atualizado com o parceiro comercial.
- Confirme que o algoritmo do certificado corresponde aos requisitos do parceiro comercial. Atualize o algoritmo nas configurações AS2 se necessário.
- Verifique se o tráfego de saída para o endpoint AS2 do parceiro comercial é permitido pelo firewall da sua rede.

Falha de conexão FTP ou SFTP

Sintoma: As transmissões FTP ou SFTP para ou de um parceiro comercial falham, ou as transferências de arquivo travam e expiram.
Possíveis causas:
- O endereço do servidor, porta, credenciais ou método de autenticação (senha vs. chave SSH) estão incorretos ou desatualizados.
- Um firewall ou restrição de rede está bloqueando a porta necessária entre o Jitterbit EDI e o servidor FTP/SFTP.
- O diretório de destino não existe ou a conta de serviço não tem permissões de leitura/escrita nele.
- A chave do host foi alterada no servidor SFTP, causando uma incompatibilidade.
Resolução:
- Revise as configurações de comunicação FTP do parceiro comercial afetado e verifique todos os parâmetros de conexão.
- Confirme que a conectividade com o endereço e porta do servidor FTP/SFTP é permitida através dos firewalls relevantes.
- Verifique se a conta de serviço tem as permissões necessárias no diretório de destino.
- Se usar autenticação por chave SSH, confirme que a chave está atual e é aceita pelo servidor. Se a chave do host foi alterada, atualize a entrada de hosts conhecidos.

Problemas de conectividade VAN

Sintoma: Documentos EDI não estão sendo entregues ou recebidos através de uma Rede de Valor Agregado (VAN).
Possível causa: Uma conexão VAN é uma conexão gerenciada que a Jitterbit configura; você não pode criá-la ou configurá-la por conta própria. Falhas de entrega geralmente envolvem a interconexão VAN, roteamento de caixa de correio ou configuração do parceiro no lado do provedor, em vez de uma configuração de autoatendimento no Jitterbit EDI.
Resolução:
- Confirme se a conexão VAN correta está atribuída ao parceiro comercial afetado.
- Como a conexão VAN não pode ser configurada diretamente do Jitterbit EDI, entre em contato com o suporte Jitterbit ou seu Gerenciador de Sucesso do Cliente para verificar a interconexão VAN e o roteamento de documentos.
- Coordene com o provedor VAN para confirmar se os identificadores de caixa de correio e o roteamento do parceiro comercial estão corretos no lado da VAN.

Documento rejeitado: Dados inválidos ou ausentes

Sintoma: um documento EDI de saída é rejeitado pelo parceiro comercial ou falha na validação, ou um documento de entrada produz uma confirmação negativa.
Possíveis causas:
- Um segmento obrigatório ou elemento de dados está ausente do documento.
- Um valor de campo excede o comprimento permitido, usa um tipo de dados incorreto ou contém caracteres inválidos.
- O indicador de uso de intercâmbio (ISA15) está definido como T (teste) em vez de P (produção), então o parceiro comercial rejeita o documento.
- O documento não está em conformidade com o guia de implementação do parceiro comercial.
Resolução: revise a transação rejeitada na página Transações para o segmento ou elemento específico citado no erro e, em seguida:
- Para um documento que você enviou, compare-o com o guia de implementação do parceiro comercial para identificar campos ausentes ou não conformes e, em seguida, atualize o mapeamento EDI e as configurações do tipo de documento afetado para produzir uma saída em conformidade.
- Para um documento de entrada enviado pelo parceiro comercial, compartilhe o erro de validação com ele para que possa corrigir seu formato de saída.

Erro de mapeamento ou esquema EDI

Sintoma: documentos EDI são gerados com conteúdo incorreto, campos ausentes ou uma estrutura inesperada, ou documentos de entrada falham no processamento correto.
Possíveis causas:
- O mapa ou esquema EDI está desatualizado e não reflete o guia de implementação atual ou os requisitos do parceiro comercial.
- Os campos de dados de origem são mapeados incorretamente, produzindo valores errados no documento de saída.
- Incompatibilidades de tipo de dados, caracteres especiais ou problemas de codificação nos dados de origem causam falhas na transformação.
Resolução:
1. Revise as configurações de EDI do parceiro comercial afetado em Configurações de EDI e verifique se o mapa reflete com precisão o guia de implementação atual.
2. Valide se os campos de dados de origem estão mapeados para os segmentos e elementos EDI corretos.
3. Verifique os dados de origem quanto a caracteres especiais, problemas de codificação ou valores inesperados que possam estar causando falhas na transformação e adicione etapas de limpeza de dados, se necessário.
4. Teste com um documento de amostra representativo e use o arquivo para comparar a saída gerada com a estrutura esperada.

Identificadores de parceiro comercial incorretos

Sintoma: Documentos são roteados incorretamente, rejeitados no nível do envelope ou não reconhecidos pelo parceiro comercial.
Possíveis causas:
- O ID EDI do remetente ou destinatário, código qualificador ou outros identificadores no nível do envelope não correspondem ao que o parceiro comercial espera.
- A configuração do parceiro comercial foi atualizada recentemente, mas a alteração não foi aplicada no Jitterbit EDI.
Resolução:
1. Revise a configuração do parceiro comercial e confirme que o ID EDI e os códigos qualificadores correspondem aos valores especificados na documentação de configuração do parceiro comercial.
2. Compare os identificadores do envelope em um documento rejeitado (visível no arquivo) com os valores esperados.
3. Atualize as configurações do parceiro comercial se algum identificador estiver incorreto e reprocesse ou reenvie os documentos afetados.

Confirmações não configuradas ou não recebidas

Sintoma: As confirmações funcionais esperadas 997 (X12) ou CONTRL (EDIFACT) não estão sendo enviadas ou recebidas, ou o processamento de confirmação não está funcionando conforme esperado.
Possíveis causas:
- A geração ou o processamento de confirmação está desabilitado nas definições EDI do parceiro comercial.
- O tipo de documento de confirmação não está incluído na configuração de fluxo de trabalho do parceiro comercial.
- O parceiro comercial não está enviando confirmações, ou as confirmações dele estão sendo roteadas incorretamente.
Resolução:
- Nas definições EDI do parceiro comercial, confirme que a geração e o processamento de confirmação estão habilitados para os tipos de documento relevantes.
- Revise a configuração de gerenciar fluxos de trabalho para confirmar que o tipo de documento de confirmação está incluído no fluxo de trabalho.
- Verifique o arquivo para determinar se as confirmações do parceiro comercial estão sendo recebidas mas não processadas, ou não estão chegando.
- Se as confirmações não estiverem chegando, coordene com o parceiro comercial para confirmar que ele as está enviando para o endpoint correto.

AS2: O firewall do parceiro comercial deve permitir endereços IP do Jitterbit

Sintoma: Um parceiro comercial relata que não consegue receber suas transmissões AS2, ou os reconhecimentos AS2 deles nunca chegam, mesmo que suas configurações AS2 de saída pareçam corretas.
Possível causa: O firewall do parceiro comercial exige uma lista de permissões explícita para tráfego de entrada e não adicionou os endereços IP do Jitterbit EDI.
Resolução:
- Forneça os seguintes endereços IP do Jitterbit EDI ao seu parceiro comercial e solicite que coloque-os na lista de permissões para tráfego AS2 de entrada e saída:
  - América do Norte: 40.71.22.62
  - EMEA e APAC: 20.166.31.85
- Para sua URL de recebimento AS2 de entrada e o endereço IP correspondente para fornecer aos parceiros comerciais, consulte a página configurações de comunicação AS2 da sua região.

A verificação de transação duplicada não se aplica ao formato EDIXml ou XCBL

Sintoma: Documentos de entrada duplicados estão sendo processados várias vezes mesmo com a configuração Verificação de Transação Duplicada ativada na conexão AS2 do parceiro comercial.
Possível causa: A Verificação de Transação Duplicada se aplica apenas a documentos em formato EDI. Ela não filtra duplicatas para os formatos de intercâmbio EDIXml ou XCBL.
Resolução: Se a filtragem de duplicatas for necessária para fluxos de trabalho EDIXml ou XCBL, implemente lógica de deduplicação na operação do Studio que processa os documentos de entrada (por exemplo, verificando um ID de transação em um registro de banco de dados ou Cloud Datastore antes do processamento).

A atividade EDI for Cloud v2 falha em um agente privado atrás de um firewall ou proxy

Sintoma: Em um agente privado, uma atividade EDI for Cloud v2 como Get Document falha ao recuperar dados (por exemplo, com um erro "Unable to fetch data"), mesmo que o teste de conexão seja bem-sucedido e o mesmo projeto funcione em um grupo de agentes na nuvem.
Possível causa: O agente privado está atrás de um firewall ou proxy que bloqueia o acesso de saída para o serviço Jitterbit eiCloud EDI em eicloudservice.com. O conector EDI for Cloud v2 chama esse serviço (por exemplo, em *.transactionapi.eicloudservice.com) para recuperar dados, portanto bloqueá-lo causa falha na atividade. Agentes na nuvem não são afetados.
Resolução:
1. Coloque na lista de permissões eicloudservice.com e seus subdomínios para acesso de saída no firewall, proxy e rede do agente privado. Para os outros domínios Jitterbit e endereços IP que um agente privado precisa para acesso de saída, consulte Informações de lista de permissões.
2. Se um proxy estiver em uso, confirme se está configurado corretamente no agente privado e não está interferindo na conexão.

Token de acesso EDI desativado causa erro `INVALID_TOKEN`

Sintoma: Operações que usam o conector EDI for Cloud v2 falham com:

Error opening connection. Exception is: Error code: INVALID_TOKEN

Possível causa: O token de acesso usado pela conexão EDI for Cloud v2 foi definido como Inativo na página Access Tokens do Management Console.
Resolução: Na página Access Tokens, localize o token e defina seu Status como Ativo.

Erro de transformação: Campo não reconhecido na atividade EDI

Sintoma: uma transformação usando uma atividade EDI for Cloud v2 (como Listar Transações) falha com um erro de análise JSON referenciando um nome de campo não reconhecido, por exemplo:
```
Unrecognized field "user_defined_field_1"
```
Possível causa: a versão do conector EDI for Cloud v2 instalada no agente está desatualizada. O serviço EDI de backend retorna um campo (como user_defined_field_1) que a versão mais antiga do conector não reconhece, portanto o conector não consegue analisar a resposta.
Resolução: atualize o conector EDI for Cloud v2 no agente para a versão mais recente, seguindo Confirmar disponibilidade do conector e mantê-lo atualizado no guia de solução de problemas do conector. Clicar em Testar Conexão na conexão EDI for Cloud v2 baixa a versão mais recente do conector para o agente; se a política organizacional Desabilitar Atualização Automática de Conector estiver habilitada, atualize o conector do grupo de agentes no Console de Gerenciamento na página Agentes.

Segmento EDI repetido ou loop mapeia apenas a última iteração

Sintoma: Em uma transformação do Studio, um segmento ou loop repetido em um documento EDI manipulado através do conector EDI for Cloud v2 mapeia apenas sua última ocorrência (iterações anteriores são descartadas), porque a cardinalidade do nó no esquema de atividade do conector é de ocorrência única (por exemplo, (0,1)) em vez de repetida ((1,many)). Isso afeta tanto X12 (por exemplo, um segmento N9 aninhado dentro de um loop LX em um 945) quanto EDIFACT (por exemplo, um grupo CNI repetido em um IFCSUM).
Possível causa: O esquema gerado automaticamente fornecido pelo conector EDI for Cloud v2 não reflete a cardinalidade correta para o segmento ou loop afetado. O documento bruto no armazenamento de Transações do EDI contém todas as iterações, e um esquema construído manualmente a partir desse XML bruto as mapeia corretamente, o que confirma o esquema de resposta do conector (não os dados) como a causa.
Resolução:
1. Abra a conexão EDI for Cloud v2 no Studio e atualize os metadados para verificar se uma correção de esquema foi lançada.
2. Se a cardinalidade ainda estiver incorreta após a atualização, exporte o esquema, atualize manualmente o atributo maxOccurs no segmento afetado em um editor XML externo e reimporte-o como um XSD personalizado.

Adicionando níveis de loop hierárquico aninhado (HL) a uma transformação EDI

Sintoma: Ao construir uma transformação do Studio para um conjunto de transações EDI que usa loops hierárquicos (por exemplo, X12 870 4010VICS, que é estruturado de forma semelhante ao 856), o esquema da atividade Enviar Documento do conector EDI for Cloud v2 mostra um único nível HL, mas o documento que você precisa produzir requer níveis HL aninhados (por exemplo, um nível de pedido HL-O com um nível de item filho HL-I).
Possível causa: Documentos hierárquicos podem aninhar níveis HL em profundidades variadas, portanto o esquema do conector expõe um único nível HL que você replica na transformação para construir os níveis adicionais que seu documento requer.
Resolução:
1. Na árvore de esquema de destino da transformação, clique com o botão direito no nó HL existente e selecione Duplicar nó para adicionar o nível HL aninhado (por exemplo, um nível HL-I filho sob HL-O).
2. Mapeie o nó duplicado para seus dados de origem. Adicione uma condição no nó duplicado se ele deve ser criado na saída apenas em circunstâncias específicas.

Valores de substituição de ID EDI não aplicados a transações de saída

Sintoma: Transações de saída usam os IDs EDI de remetente ou destinatário padrão da configuração do parceiro comercial, em vez dos IDs de substituição preferidos configurados nas definições de ID EDI.
Possível causa: As substituições de ID EDI não são aplicadas automaticamente. Os IDs preferidos devem ser mapeados explicitamente na transformação de solicitação da operação do Studio que envia o documento de saída usando o conector EDI for Cloud v2.
Resolução: Nessa transformação de solicitação, mapeie valores para estes campos para aplicar os IDs preferidos (consulte a página Definições de ID EDI para os valores exatos a usar):
- ISA05_ID_Qualifier: qualificador de ID do remetente
- ISA06_Sender_ID: ID EDI do remetente
- ISA07_ID_Qualifier: qualificador de ID do destinatário
- ISA08_Receiver_ID: ID EDI do destinatário

Não é possível excluir uma conexão de comunicação atribuída

Sintoma: A tentativa de excluir uma conexão AS2 ou FTP nas Definições de comunicação falha ou a opção de exclusão não está disponível.
Possível causa: Conexões atribuídas não podem ser excluídas. Uma conexão que está atualmente atribuída a um parceiro comercial deve ser desatribuída antes de poder ser removida.
Resolução:
1. Nas Definições de comunicação, selecione o parceiro comercial que usa a conexão e atribua uma conexão diferente a esse parceiro.
2. Quando nenhum parceiro estiver usando a conexão, a opção de exclusão fica disponível.

FTP "Próximo Tempo de Execução" não atualiza sem atualizar a página

Sintoma: A Próxima execução exibida nas definições de comunicação FTP de um parceiro comercial permanece desatualizada após a execução do trabalho FTP agendado, mesmo que o agendamento esteja funcionando corretamente.
Possível causa: A interface atualiza o status de trabalhos agendados apenas quando a página é carregada ou quando uma ação manual dispara um recarregamento de dados. Ela não faz sondagem do mecanismo em tempo real.
Resolução:
- Atualize a página do navegador para atualizar a exibição de Próxima execução.
- Como alternativa, navegue para longe das definições de FTP e volte para forçar um recarregamento.

Adição de ID EDI ou ID Preferido falha: ID já em uso

Sintoma: A adição de um ID EDI ou um ID preferido a um parceiro comercial falha, mesmo quando o ID não parece estar em uso no ambiente atual. Uma das seguintes mensagens é exibida:

Não é possível adicionar ID EDI [ID] pois ele já está em uso; confirme e forneça um ID único.

Não é possível adicionar ID Preferencial [ID] pois ele já está em uso; confirme e forneça um ID único.

Possíveis causas:
- Cada ID EDI deve ser único em todos os ambientes Harmony onde o Jitterbit EDI está habilitado. Se o mesmo ID já estiver atribuído a um parceiro comercial em um ambiente diferente, a adição falha.
- Um ID Preferencial deve ser único dentro do ambiente. É rejeitado se já estiver atribuído ao mesmo parceiro comercial ou a outro parceiro comercial no mesmo ambiente.
Resolução:
- Para um ID EDI duplicado, verifique todos os outros ambientes Harmony onde o EDI está habilitado para confirmar se o ID já está atribuído lá. Trabalhe com seu parceiro comercial para estabelecer um ID EDI único para cada ambiente onde você troca documentos e use um ID distinto para ambientes de não produção que difira do seu ID EDI de produção.
- Para um ID Preferencial duplicado, verifique a lista de ID Preferencial (IDs ISA) do parceiro comercial atual e de outros parceiros comerciais no mesmo ambiente, depois escolha um ID único.

Documentos de saída passam na validação local mas falham no teste do parceiro comercial

Sintoma: Documentos EDI de saída passam na verificação de validação local no Jitterbit EDI mas são rejeitados durante o teste ou certificação do parceiro comercial, frequentemente com erros sobre elementos ausentes ou não conformes.
Possíveis causas:
- A validação de saída está desabilitada na configuração do fluxo de trabalho. O Jitterbit EDI permite que documentos sejam gerados sem validação, mas sem ela, os documentos podem não ter elementos exigidos pelo guia de implementação do parceiro comercial.
- As configurações EDI cobrem os elementos essenciais do padrão, mas o guia de implementação do parceiro comercial pode exigir elementos obrigatórios adicionais não aplicados pelas configurações padrão.
Resolução:
- Na configuração de gerenciar fluxos de trabalho, habilite a validação para o fluxo de trabalho de saída.
- Revise o guia de implementação do parceiro comercial para qualquer elemento obrigatório além das configurações EDI padrão e adicione-os ao mapeamento.
- A menos que você tenha uma compreensão profunda da transação EDI específica e dos requisitos do parceiro comercial, sempre habilite a validação antes de testar com um parceiro comercial.

Transação arquivada mais cedo ou mais tarde do que o esperado

Sintoma: Uma transação é arquivada antes do período de retenção esperado terminar, ou permanece disponível por mais tempo do que o esperado.
Possível causa: As transações são arquivadas com base na data posterior entre duas datas: a data da transação e a data do documento. Se a data do documento for mais recente que a data da transação, o arquivamento é calculado a partir da data do documento, o que pode estender o período de retenção.
Resolução:
- Ao investigar o tempo de arquivamento inesperado, verifique tanto a data da transação quanto a data do documento da transação afetada.
- Revise as configurações de período de retenção para confirmar o número de dias configurado (30, 60 ou 90).

Não é possível acessar recursos EDI

Sintoma: Um usuário não consegue visualizar ou interagir com páginas EDI, ou certas ações EDI não estão disponíveis.
Possíveis causas:
- O acesso EDI requer tanto uma permissão de função específica do EDI (Admin, EDI User ou EDI Viewer) quanto uma função de acesso ao ambiente em nível Write. A falta de qualquer uma delas impede o acesso.
- As funções EDI User e EDI Viewer diferem no que permitem. EDI Viewer pode reprocessar transações, reenviar confirmações e ler páginas, mas não pode criar ou atualizar configurações ou fazer upload de arquivos. Criar ou atualizar configurações e fazer upload de arquivos para processamento requerem a função EDI User. Ações administrativas, como arquivar transações, habilitar PII e alterar configurações de limpeza, requerem a função Admin.
Resolução:
- No Management Console, verifique se o usuário tem uma função que inclui a permissão Admin, EDI User ou EDI Viewer.
- Confirme que o nível de acesso do ambiente do usuário inclui acesso Write para o ambiente onde o EDI está configurado.
- Se o usuário precisar executar operações de escrita (como criar parceiros comerciais ou fazer upload de documentos), atribua a função EDI User em vez de EDI Viewer. Consulte Permissões EDI para a matriz de permissões completa.

Não é possível ativar configurações de PII

Sintoma: A opção para ativar configurações de PII (informações de identificação pessoal) para um parceiro comercial está indisponível ou desativada.
Possível causa: Ativar configurações de PII requer a permissão Admin permission. Nem a função EDI User nem a EDI Viewer podem ativar configurações de PII.
Resolução:
- Confirme se a função do usuário inclui a permissão Admin, não apenas EDI User ou EDI Viewer.
- Se o usuário precisar gerenciar configurações de PII regularmente, atualize a atribuição de função de acordo.

Desenvolvimento de aplicativos

Esta seção aborda problemas com a capacidade de desenvolvimento de aplicativos do Harmony: criar, implantar e executar aplicativos no App Builder.

App Builder falha ao iniciar com erro 500

Sintoma: O App Builder não inicia no IIS e retorna um erro HTTP 500.
Possível causa: O Pacote de Hospedagem do Runtime ASP.NET Core que o App Builder requer não está instalado no servidor Windows, portanto, o IIS não consegue iniciar o aplicativo.
Solução:
1. Instale o Pacote de Hospedagem do Runtime ASP.NET Core necessário para o App Builder, conforme listado nos Requisitos do sistema.
2. Reinicie o IIS e verifique se o App Builder carrega corretamente.

App Builder falha ao iniciar com erro HTTP 500.30

Sintoma: O App Builder não inicia e retorna:

HTTP Error 500.30 - ASP.NET Core app failed to start

Possível causa: A identidade do pool de aplicativos do IIS não tem acesso total à pasta raiz do App Builder, portanto, o aplicativo não consegue iniciar.
Solução:
1. Conceda à identidade do pool de aplicativos do App Builder (por padrão, IIS AppPool\Vinyl) Controle total da pasta raiz do App Builder. Veja Definir permissões.
2. Reinicie o pool de aplicativos e, em seguida, recarregue o App Builder.

App Builder retorna erro HTTP 503

Sintoma: Abrir o App Builder retorna:

HTTP Error 503. The service is unavailable.

Possível causa: O pool de aplicativos do IIS para o App Builder está parado.
Solução:
1. Abra o Gerenciador do IIS e selecione Pools de Aplicativos.
2. Selecione o pool de aplicativos do App Builder (por padrão, Vinyl), e em seguida selecione Iniciar.
Nota

Se o pool de aplicativos parar novamente imediatamente após iniciar, é provável que o App Builder esteja falhando na inicialização. Revise os logs da aplicação e o Visualizador de Eventos do Windows para o erro subjacente.

App Builder inicia mas não cria bancos de dados

Sintoma: O App Builder inicia com sucesso, mas nenhum banco de dados é criado no SQL Server.
Causa possível: O arquivo de conexão tem uma extensão incorreta (por exemplo, .txt em vez de .xml).
Solução: Localize o arquivo de conexão do App Builder e confirme se ele usa a extensão .xml. Renomeie o arquivo se a extensão estiver incorreta e, em seguida, reinicie o App Builder. Se o App Builder iniciar, mas retornar um erro de conexão em vez de criar silenciosamente nenhum banco de dados, consulte Ocorre um erro ao carregar as informações de conexão do banco de dados.

Ocorre erro ao carregar as informações de conexão do banco de dados

Sintoma: O App Builder retorna o seguinte erro:

An error occurred while attempting to load the database connection information.

Causa possível: O arquivo Connection.xml está ausente ou contém dados de conexão incorretos.
Solução:
- Substitua ou atualize o Connection.xml com os dados de conexão corretos e, em seguida, reinicie o App Builder. Consulte Criar um arquivo de conexão.
- Se o App Builder iniciar sem erro, mas não criar bancos de dados, consulte O App Builder inicia, mas não cria bancos de dados.

App Builder carrega com estilos ausentes ou quebrados

Sintoma: O App Builder inicia, mas as páginas são renderizadas com estilo ausente ou quebrado (CSS).
Possível causa: O arquivo ZIP de instalação não foi desbloqueado antes de ser extraído. O Windows marca arquivos baixados de outro computador como bloqueados (a "marca da web"), e extrair um arquivo ainda bloqueado propaga essa marca para os arquivos extraídos, o que pode impedir que os ativos de estilo do App Builder sejam carregados corretamente.
Resolução:
1. Exclua os arquivos extraídos.
2. Desbloqueie o arquivo ZIP original: clique com o botão direito nele, selecione Propriedades, abra a aba Segurança e selecione Desbloquear. Veja Obter e descompactar o software.
3. Extraia o ZIP novamente e reinicie a instalação ou atualização.

Falha no upload da licença

Sintoma: O upload de um arquivo de licença falha com um dos seguintes erros:

An unknown error occurred.

405 POST Method not allowed

Failed to deserialize license (d3fc6d4e835e)

Possível causa: O WebDAV está instalado ou habilitado no IIS e pode interferir na solicitação POST usada para fazer o upload da licença.
Resolução:
1. Desinstale ou desative o módulo WebDAV no IIS.
2. Tente fazer o upload da licença novamente.
3. Se o WebDAV for necessário para outros aplicativos no servidor, entre em contato com o suporte da Jitterbit para obter orientações sobre como configurar ambos os serviços para coexistirem.

App Builder não inicia automaticamente após reinicialização do servidor

Sintoma: O App Builder não se torna disponível automaticamente após a reinicialização do servidor Windows, exigindo uma solicitação manual inicial para inicializar o aplicativo.
Resolução: Para os passos de resolução, veja Solução de problemas do comportamento de inicialização automática.

Implantação Docker: Licença do App Builder 4.x não pode ser carregada na interface

Sintoma: Após atualizar do Vinyl 3.3 para o App Builder 4.x no Docker, o carregamento da licença do App Builder pela interface do usuário do App Builder falha ou a opção não está disponível.
Possível causa: Implantações do App Builder 4.x no Docker não suportam o carregamento de licença pela interface do usuário.
Resolução: Forneça a licença através de um dos seguintes métodos:
- No arquivo docker-compose.yml, defina a variável de ambiente License__LicenseKey com a chave de licença do App Builder 4.x codificada em base64.
- Adicione a chave de licença ao arquivo appsettings.json no subdiretório data do diretório de composição do Docker.

Alta disponibilidade: Todas as instâncias devem usar o mesmo `appsettings.json`

Sintoma: Em uma implantação de alta disponibilidade, alguns nós do App Builder se comportam de maneira diferente de outros (por exemplo, a autenticação funciona em alguns nós, mas não em outros, ou as chaves de criptografia de dados são inconsistentes entre os nós).
Possível causa: Cada instância do App Builder em uma implantação de alta disponibilidade deve usar um arquivo de configuração appsettings.json idêntico. Se os arquivos diferirem entre as instâncias, o comportamento será inconsistente entre os nós.
Resolução:
- Confirme que todas as instâncias do App Builder na implantação de HA possuem arquivos appsettings.json idênticos.
- Após alterar a configuração em uma instância, aplique a mesma alteração a todas as outras instâncias e reinicie cada uma.

Falha no login SSO ou redirecionamento para URL incorreta

Sintoma: Usuários que tentam fazer login via single sign-on (SSO) encontram um erro de redirecionamento ou são enviados para uma URL inesperada.
Possíveis causas:
- O URI de Redirecionamento configurado no Provedor de Identidade (IdP) não corresponde à URL que o App Builder está usando.
- Um proxy reverso ou balanceador de carga na frente do App Builder (por exemplo, IIS atrás de um F5) encerra o TLS, então o App Builder vê http enquanto a URL pública usa https. O URI de Redirecionamento então usa o protocolo errado e não corresponde ao valor registrado no IdP.
- A URL de integração SSO no App Builder faz referência a um endereço desatualizado ou incorreto.
- O provedor de segurança OpenID Connect no App Builder está mal configurado.
Resolução:
- No IdP (por exemplo, Okta ou Azure AD), confirme que o URI de Redirecionamento corresponde exatamente à URL do aplicativo App Builder, incluindo o protocolo (https://) e qualquer caminho.
- No App Builder, revise a configuração do provedor de segurança em IDE > Provedores de Segurança e verifique se as configurações do OpenID Connect correspondem aos valores esperados pelo IdP.
- Se a URL do App Builder mudou (por exemplo, após uma migração ou atualização de domínio), atualize o URI de Redirecionamento tanto no App Builder quanto no IdP.

Sintoma: Abrir a URL base de um ambiente do App Builder (por exemplo, https://example.com/) não redireciona para a página de login. Visitantes não autenticados são levados diretamente a um aplicativo em vez disso.
Possível causa: O usuário anonymous integrado tem acesso à página inicial de um aplicativo. O App Builder redireciona automaticamente cada usuário para uma página inicial à qual eles podem acessar, então, quando o usuário anonymous pode acessar a página inicial de um aplicativo, todos os visitantes não autenticados são redirecionados para lá em vez de para a página de login.
Resolução: Remova o acesso do usuário anonymous à página inicial do aplicativo para que os visitantes não autenticados sejam direcionados para a página de login.

Usuários locais não conseguem redefinir uma senha esquecida

Sintoma: Usuários locais não conseguem redefinir uma senha esquecida. O link Esqueceu a Senha na tela de login está ausente ou não completa a redefinição.
Possível causa: O grupo Usuários Anônimos não recebeu acesso ao aplicativo de redefinição de senha, então usuários não autenticados não conseguem acessar o fluxo de trabalho de redefinição de senha.
Resolução: Conceda ao grupo Usuários Anônimos acesso ao aplicativo App Builder - Redefinição de Senha e adicione-o ao papel Redefinição de Senha. Veja Redefinição de senha para os passos completos de configuração, incluindo a configuração SMTP necessária.

App Builder está lento ou não responde

Sintoma: O App Builder responde lentamente às interações do usuário, ou o carregamento da página e as consultas estão expirando.
Causas possíveis:
- O servidor do App Builder possui recursos de CPU ou memória insuficientes para a carga atual.
- Um problema de rede entre o usuário e o servidor do App Builder, como largura de banda limitada, perda de pacotes ou um firewall, está desacelerando a transmissão de dados.
- Consultas ou lógica de aplicação não otimizadas estão produzindo páginas lentas, ou um serviço em segundo plano está consumindo recursos excessivos.
- O processo de trabalho do IIS entrou em um estado não saudável.
- Uma operação de longa duração excedeu o tempo limite de um proxy, balanceador de carga ou outro dispositivo de rede entre o navegador e o App Builder, que então desconectou o navegador. O navegador relata um erro como 504 Gateway Timeout, mas a operação continua a ser executada no servidor e pode ainda ter sucesso ou falhar após a desconexão do navegador.
Resolução:
- Revise a utilização de recursos do servidor (CPU, memória, I/O de disco) para identificar qualquer saturação de recursos.
- Para descartar um problema de rede, conecte-se a partir de uma rede diferente (por exemplo, outra rede Wi-Fi ou um dispositivo móvel em uma conexão celular) e execute um teste de velocidade da internet. Se o desempenho melhorar em outra rede, a causa provavelmente é largura de banda limitada, um problema com o ISP ou um firewall, em vez do próprio App Builder.
- Verifique os logs da aplicação em busca de erros recorrentes, timeouts ou avisos que possam indicar a causa.
- Se o navegador relatou um timeout de gateway, use o histórico de eventos para determinar se a operação foi concluída no servidor antes de você tentar novamente. Como a operação continua a ser executada após a desconexão do navegador, tentar novamente pode duplicar o trabalho.
- Revise os serviços em segundo plano ativos e o histórico de eventos em busca de trabalhos de longa duração ou travados. Para identificar consultas SQL lentas especificamente, veja Capturar e analisar consultas lentas.
- Para páginas lentas causadas por consultas ou lógica de aplicação não otimizadas, veja Ajuste de desempenho do App Builder para orientação sobre otimização de consultas, indexação e design de aplicação.
- Se o servidor parecer saudável, mas o App Builder continuar não respondendo, recicle o pool de aplicativos do IIS para o App Builder.
- Se o problema for intermitente e difícil de diagnosticar, recupere um dump de processo para análise adicional. Veja Recuperar um arquivo de dump.

Falha na autenticação OAuth do Salesforce ou autentica com a instância incorreta

Sintoma: Usuários que fazem login com SSO do Salesforce são inesperadamente autenticados com a instância errada do Salesforce, ou os tokens do Salesforce param de funcionar e os usuários são solicitados a reautenticar repetidamente.
Possíveis causas:
- Múltiplas instâncias do App Builder compartilham o mesmo Aplicativo Conectado do Salesforce. O Salesforce retém apenas os quatro tokens de atualização mais recentes por Aplicativo Conectado. Quando um quinto token é emitido, o mais antigo é invalidado, fazendo com que a instância que possui esse token perca a autenticação.
- Múltiplas instâncias do Salesforce estão configuradas no App Builder, e o navegador do usuário já possui uma sessão ativa com uma instância do Salesforce. Quando o usuário tenta fazer login em uma segunda instância, o Salesforce reutiliza a sessão existente e faz o login do usuário na primeira instância em vez disso.
Resolução:
- Atribua um Aplicativo Conectado do Salesforce separado para cada instância do App Builder para evitar conflitos de tokens de atualização. Veja a documentação do provedor de segurança do Salesforce para detalhes de configuração.
- Se um usuário estiver sendo autenticado com a instância errada do Salesforce, peça ao usuário para sair de todas as sessões ativas do Salesforce em seu navegador antes de tentar fazer login novamente.

Valores de coluna criptografada aparecem em branco após reconfiguração da fonte de dados

Sintoma: Valores armazenados em uma coluna criptografada aparecem em branco (nulo) no aplicativo após uma fonte de dados, tabela ou coluna ter sido excluída e recriada, ou após a atualização ou migração do ambiente do App Builder.
Possíveis causas:
- O App Builder deriva a chave de criptografia de cada coluna dos valores DataSourceId, TableId e ColumnId em seu modelo lógico. Se algum desses identificadores mudar (por exemplo, após excluir e recriar uma fonte de dados, tabela ou coluna), os valores criptografados existentes não poderão mais ser descriptografados. Nenhum erro é exibido: o valor aparece silenciosamente como nulo.
- Durante uma atualização ou migração, a pasta keys da instalação anterior não foi copiada para a nova pasta de instalação, então o App Builder não consegue acessar o material da chave necessário para descriptografar os valores existentes.
Resolução:
- Se os valores criptografados aparecerem em branco após uma atualização ou migração, confirme que o conteúdo da pasta keys foi copiado da pasta de instalação anterior para a nova. Veja a etapa 5 de Restaurar configurações.
- Para evitar perda de dados devido a mudanças de identificadores, evite excluir e recriar fontes de dados, tabelas ou colunas criptografadas que contenham dados. Para uma lista completa de limitações de criptografia, veja Criptografia de coluna em nível de aplicativo.
- Antes de fazer alterações estruturais, exporte ou faça backup de quaisquer valores de coluna criptografada.
- Se os identificadores já mudaram e os dados não puderem ser recuperados de um backup, entre em contato com o suporte da Jitterbit com detalhes da configuração original.

Falha na população da linha de base do log de auditoria

Sintoma: Preencher a linha de base do Log de Auditoria Completo gera um erro e a linha de base não é criada.
Causa possível: A tabela não possui uma chave primária UUID de uma única parte. O Log de Auditoria Completo requer um UUID único para cada registro, portanto, tabelas com uma chave primária composta (de várias partes) não são auditadas por padrão. Para auditar tal tabela, você deve primeiro adicionar uma coluna de auditoria UUID.
Resolução:
1. Adicione uma coluna UUID à tabela e defina seu tipo de uso de coluna como Auditoria, em seguida, preencha-a para registros existentes. Para o procedimento completo, consulte Outras configurações de chave primária.
2. Navegue até Painel de Ação > IDE > Configurações Adicionais e clique no botão Preencher Registros de Auditoria.
3. Localize a fonte de dados do aplicativo, clique em Preencher Tudo (ou Preencher em tabelas individuais), em seguida, clique em Prosseguir para tentar novamente.

Nota

A Auditoria Completa não falha em colunas grandes ou binárias. Valores de string com mais de 700 caracteres são auditados, mas truncados além de 700 caracteres, e colunas binárias são auditadas pelo tamanho do arquivo em vez do conteúdo.

Sistema de arquivos do SharePoint: Autenticação OAuth obrigatória a partir de abril de 2026

Sintoma: Conexões do Sistema de Arquivos SharePoint falham na autenticação ou não podem ser criadas.
Possível causa: A partir de 30 de abril de 2026, conexões do Sistema de Arquivos SharePoint requerem autenticação OAuth. Conexões usando autenticação legada não funcionam mais.
Resolução:
1. Atualize para o App Builder 4.61 ou posterior.
2. Siga o guia de conexão OAuth do Microsoft SharePoint para configurar um provedor de segurança OAuth antes de criar ou atualizar o servidor de dados.

Sistema de arquivos do SharePoint: Arquivos não exibidos ou caminhos retornam erros

Sintoma: Uma fonte de dados do Sistema de Arquivos SharePoint está conectada com sucesso, mas os arquivos não são exibidos, o conteúdo não é renderizado ou um caminho de diretório causa um erro.
Possíveis causas:
- O App Builder só pode acessar arquivos armazenados no diretório Documentos. Arquivos em outros diretórios do SharePoint não são acessíveis.
- Nomes de arquivos são sensíveis a maiúsculas e minúsculas ao vincular entre fontes de dados. Uma discrepância de caixa entre o nome do arquivo do SharePoint e o nome usado em outra fonte de dados impede a renderização do conteúdo.
- Usar uma barra (/) em um caminho de diretório em um objeto de negócios causa um erro.
Resolução:
- Confirme que os arquivos estão armazenados no diretório Documentos no SharePoint.
- Verifique se os nomes de arquivos usados em objetos de negócios e vinculações de fontes de dados correspondem exatamente à caixa dos nomes de arquivos do SharePoint.
- Ao especificar um caminho de diretório em um objeto de negócios, use barras invertidas (\) em vez de barras (/) . Por exemplo, use \documents\employees em vez de /documents/employees.

App Builder Connector: Chave de API gerada não pode ser recuperada após sair da tela

Sintoma: Um usuário do conector configurou o Conector do App Builder, mas o valor da chave da API não está mais disponível após navegar para fora da tela de geração da chave.
Possível causa: A chave da API gerada é exibida apenas uma vez na tela Gerar Chave. Uma vez que você sai da tela, o valor não pode ser recuperado.
Resolução:
- Copie o valor da chave para a área de transferência imediatamente após ser gerado, antes de navegar para fora.
- Se a chave não foi copiada, gere uma nova chave.

App Builder Connector: Erro 403 Forbidden

Sintoma: Conectar a um ambiente remoto do App Builder usando o Conector do App Builder retorna um erro 403 Proibido.
Possível causa: A conta de usuário configurada para o conector não recebeu a função Conector Remoto do App Builder no ambiente de origem do App Builder.
Resolução:
1. No ambiente de origem do App Builder, abra a conta de usuário utilizada pelo conector.
2. Atribua a função Conector Remoto do App Builder a esse usuário.

Webhook: HTTP Basic Auth requer o cabeçalho Authorization no payload

Sintoma: Um webhook configurado para usar Autenticação HTTP Básica não processa os payloads recebidos corretamente.
Possível causa: O método Autenticação HTTP Básica requer que o cabeçalho Authorization esteja presente no payload recebido. Sistemas de terceiros que omitem esse cabeçalho não se autenticam corretamente.
Resolução: Use o método de autenticação Chave da API para o provedor de segurança do webhook em vez de Autenticação HTTP Básica. O método Chave da API não requer o cabeçalho Authorization e é mais amplamente compatível com remetentes de webhook externos.

Migração de data expira em conjuntos de dados grandes

Sintoma: Uma operação de migração de data não é concluída e falha com um erro de tempo limite.
Causa possível: As migrações de data são executadas como uma única transação de banco de dados durante uma atualização de aplicativo ou fonte de dados. Com grandes conjuntos de dados, a transação pode exceder o tempo limite de comando padrão do banco de dados.
Solução: No arquivo Connection.xml do App Builder, aumente o valor de CommandTimeOut para permitir mais tempo para a conclusão da transação de migração.

Servidor de aplicativos e servidor de banco de dados do App Builder devem usar o mesmo fuso horário

Sintoma: Os valores DateTime no aplicativo estão deslocados por compensações inesperadas, ou os horários exibidos no App Builder diferem do que é mostrado no banco de dados.
Causa possível: O servidor de aplicativo do App Builder e o servidor de banco de dados estão configurados com fusos horários diferentes. Esses servidores devem estar sincronizados para que os valores DateTime sejam renderizados corretamente.
Solução:
1. Confirme que o servidor de aplicativo do App Builder e todos os servidores de banco de dados estão configurados para o mesmo fuso horário.
2. No App Builder, defina o Fuso Horário Padrão da Fonte de Dados em cada servidor de fonte de dados e o Fuso Horário em cada fonte de dados para corresponder ao fuso horário do servidor de banco de dados. Consulte Fusos horários para etapas de configuração.

Erros de configuração SMTP

Sintoma: O App Builder não consegue enviar notificações por e-mail, e os logs do aplicativo ou a saída do Testar E-mail mostram um dos seguintes erros:

Argument passed in is not serializable. Parameter name: value

Value cannot be null. ParameterName: From Address

Unknown URI scheme. Parameter name: uri

Authentication required

Causas possíveis:
- O campo Endereço de Origem do servidor de notificação SMTP está vazio, nulo ou usa um endereço de e-mail inválido (produz os dois primeiros erros acima).
- O campo URI usa um formato inválido ou esquema não suportado (produz o erro "Esquema de URI desconhecido"). O URI deve usar o esquema smtp:// ou smtps://, por exemplo smtp://mail.exemplo.com:587.
- Os campos Nome de Usuário ou Senha contêm credenciais incorretas (produz o erro "Autenticação necessária").
Resolução: No IDE, nas opções Conectar, abra Servidores de Notificação, em seguida, abra o registro do servidor SMTP e verifique o campo que corresponde ao erro que você recebeu:
- Verifique se o Endereço de Origem é um endereço de e-mail válido permitido para enviar e-mails através do host SMTP configurado.
- Verifique se o URI usa o formato smtp://<hostname>:<port> ou smtps://<hostname>:<port>. Veja Configurar SMTP para protocolos e formatos suportados.
- Verifique se o Nome de Usuário e a Senha correspondem às credenciais do servidor SMTP.
- Após fazer uma alteração, use o recurso Testar E-mail na janela do servidor de notificação para confirmar as configurações antes de implantá-las em um fluxo de trabalho.

Links profundos deixam de funcionar após renomear um aplicativo ou página

Sintoma: Um link profundo que anteriormente direcionava os usuários para um aplicativo ou página específica não funciona mais.
Causa possível: Renomear um aplicativo ou página no App Builder altera o caminho da URL usado nos links profundos. Qualquer link existente que contenha o antigo nome do aplicativo ou página não é mais válido.
Resolução:
- Atualize quaisquer sistemas externos, e-mails, portais ou favoritos que contenham a antiga URL do link profundo para usar o novo nome do aplicativo ou página.
- Construa o novo link profundo navegando até a página de destino no App Builder e copiando a URL da barra de endereços do navegador, removendo a string de consulta (tudo a partir de ?) para obter a URL canônica.
- Para evitar esse problema no futuro, use o campo Label para nomes de exibição e mantenha o campo Name (que determina o caminho da URL) curto e estável.

Um evento é acionado várias vezes ao salvar, inserir, atualizar ou excluir

Sintoma: Um evento que deveria ser acionado uma vez é acionado várias vezes na mesma ação do usuário, resultando em registros duplicados, notificações duplicadas ou outros efeitos colaterais repetidos.
Causas possíveis:
- A ação ou validação do evento está registrada tanto na camada de dados quanto na camada de lógica de negócios simultaneamente. O App Builder permite essa configuração, mas aciona o evento uma vez por registro de camada.
- O vínculo da ação está desvinculado ou está vinculado a mais de um registro. A ação é acionada uma vez para cada registro em escopo.
Resolução: Abra o App Workbench, localize a configuração do evento e, em seguida, aborde a causa que se aplica:
- Determine se a lógica pertence à camada de dados (para comportamento em toda a tabela) ou à camada de lógica de negócios (para comportamento específico da página). Consulte Configurar eventos para orientações e remova o registro duplicado da camada à qual não pertence.
- Revise o vínculo da ação. Se estiver desvinculado ou vinculado a mais de um registro, limite-o ao único registro pretendido. Consulte Vinculação implícita e explícita.

O usuário não consegue acessar as páginas ou recursos esperados

Sintoma: Um controle de ícone HTML em uma página não respeita as permissões de função de um usuário. Por exemplo, um ícone que deveria estar desativado para usuários sem permissão permanece ativo.
Possível causa: Ícones HTML se comportam como botões. Sem um evento anexado, as permissões baseadas em função não se aplicam ao ícone, portanto, ele permanece visível e ativo, independentemente da função do usuário.
Resolução:
1. Anexe um evento vazio ao controle de ícone HTML para que a visibilidade baseada em função se aplique.
2. Especifique o acesso apropriado (por exemplo, Atualizar) na função para os usuários que devem ver o ícone.

O ícone de auditoria não aparece em uma página

Sintoma: O botão ou ícone de Auditoria usado para visualizar os logs de Auditoria Completa não está visível em um painel de Formulário ou Grade.
Possíveis causas:
- O usuário não pertence à função App Builder - Administradores ou à função App Builder - Auditoria.
- O painel da página não tem Mostrar Auditoria habilitado, ou o painel não é um painel de Formulário ou Grade.
Resolução:
- Confirme que o usuário pertence à função App Builder - Administradores ou à função App Builder - Auditoria. Veja Segurança.
- Em um painel de Formulário ou Grade, habilite Mostrar Auditoria para o painel da página. Veja Habilitar auditoria completa em uma página.

Aplicativo offline: o banco de dados local é apagado quando o aplicativo é atualizado

Sintoma: Após um aplicativo offline ser atualizado, todos os dados armazenados localmente no dispositivo móvel desaparecem.
Causa possível: O banco de dados local de um aplicativo offline é apagado sempre que o aplicativo é atualizado. Esta é uma limitação conhecida dos aplicativos offline.
Solução:
- Certifique-se de que todos os dados coletados localmente estejam totalmente sincronizados com o servidor antes que uma atualização do aplicativo seja implantada.
- Informe os usuários sobre as atualizações planejadas com antecedência para que possam sincronizar antes que a atualização entre em vigor.

Aplicativo offline: os agendamentos em segundo plano não são executados quando o aplicativo está fechado

Sintoma: Tarefas agendadas ou processos em segundo plano em um aplicativo offline não estão sendo executados em um dispositivo móvel quando esperado.
Causa possível: As agendas em segundo plano não são executadas quando o aplicativo App Builder está fechado no dispositivo móvel. As agendas só são executadas enquanto o aplicativo está aberto.
Solução:
- Informe os usuários que o processamento em segundo plano agendado requer que o aplicativo permaneça aberto.
- Redesenhe fluxos de trabalho que dependem de agendas em segundo plano para serem acionados pela interação do usuário ou mova o processamento agendado para o lado do servidor.

O aplicativo móvel congela, falha ou tem problemas de link

Para problemas com o aplicativo móvel do App Builder, consulte Solução de problemas do aplicativo móvel.

Para problemas de configuração de widget e arquivo zip, consulte Solução de problemas de widget.

Solução de problemas no Jitterbit Harmony

Etapas de diagnóstico

Verificar os logs de operação

Verificar os logs de API

Verificar os logs do agente

Verificar o status do sistema Harmony

Administração da plataforma

Não conseguir fazer login no Harmony

Conta bloqueada após tentativas de login falhadas

Usuário não consegue acessar um ambiente ou seus recursos

Variáveis de projeto não transferidas durante a promoção de ambiente

Alternar o grupo de agentes de um ambiente falha com erro de versão mínima de agente

Design Studio: usuários de SSO fora da região da organização não conseguem fazer login

Teste de configuração de SSO bloqueia a conta do provedor de identidade

Política de lista de permissões de IP bloqueia um administrador

Alterar subdomínio de API quebra integrações de API existentes

O acesso do usuário externo ao API Portal expira em um momento inesperado

Alterações de ambiente não refletidas em aplicações Harmony

A configuração de SSO requer clientes WMC e Studio

Lista de bypass de SSO: membros da organização existentes não podem ser adicionados diretamente

SSO não pode ser habilitado: usuário pertence a várias organizações

SSO redireciona para login em loop sem erro

Falha na exclusão de armazenamento do Cloud Datastore com erro "cannot be excluded"

Token de acesso não pode ser editado após seu ambiente ser excluído

Expiração do token de atualização OAuth causa falha em operações conectadas

API de Log de Auditoria: falha na recuperação de token quando TFA está ativado

Falha ao adicionar um usuário externo com erro 409 conflict

A região da organização não pode ser alterada no local

Integração e automação

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

Operações agendadas não sendo executadas

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

Falhas de conexão e autenticação

Certificado Salesforce: incompatibilidade de Subject Alternative Name (SAN)

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

Falha ao carregar certificado do cliente em agentes privados Linux

Erros de transformação e dados

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

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

Caracteres especiais em esquemas JSON fornecidos por conectores

Caracteres multibyte corrompidos em uma resposta grande do conector

Esquemas espelhados com grupos de substituição

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

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

Aviso de subelemento extra nos logs de operação

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

Campos mapeados em branco com esquemas de fonte simples

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

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

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

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

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

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

Erros de script e função

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

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

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

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

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

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

Limite de iterações do loop de script excedido

RunOperation para de executar após 50 chamadas síncronas em um loop While

Comparar uma string com um número produz resultados inesperados

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

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

CallStoredProcedure: resultSet sempre nulo com drivers ODBC

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

DBLoad: Requer um driver de banco de dados JDBC

AESDecryption falha com dados criptografados no OpenSSL 3

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

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

IsNull retorna false para strings vazias de dados de origem JSON

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

Aritmética decimal produz resultados inesperados de ponto flutuante

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

Valor em cache expira mais cedo do que o esperado

RunXSLT falha com "XML version must be 1.0 or 1.1"

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

A saída de HexToBinary parece inalterada quando registrada

SortArray classifica nomes de arquivo lexicograficamente, não cronologicamente

Falha ao adicionar um usuário externo com erro `409 conflict`

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

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

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

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

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

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

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

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

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

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

`RunOperation` para de executar após 50 chamadas síncronas em um loop `While`

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

`DBExecute`: Erro quando `auto_commit` e `transaction` são ambos `true`

`CallStoredProcedure`: `resultSet` sempre nulo com drivers ODBC

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

`DBLoad`: Requer um driver de banco de dados JDBC

`AESDecryption` falha com dados criptografados no OpenSSL 3

`IsNull` retorna false para strings vazias de dados de origem JSON

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

`RunXSLT` falha com "XML version must be 1.0 or 1.1"

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

A saída de `HexToBinary` parece inalterada quando registrada

`SortArray` classifica nomes de arquivo lexicograficamente, não cronologicamente

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

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

`RunOperation` para de executar após 50 chamadas síncronas em um loop `While`

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

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

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

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

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

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

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

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

`DBExecute`: Erro quando `auto_commit` e `transaction` são ambos `true`

`CallStoredProcedure`: `resultSet` sempre nulo com drivers ODBC

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

`DBLoad`: Requer um driver de banco de dados JDBC

`AESDecryption` falha com dados criptografados no OpenSSL 3

Saída de transformação JSON omite campos `null` e strings vazias

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