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 capacidade 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 ativado, 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 arquivos.

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, consulte 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 incógnita 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, portanto 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), portanto 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 habilitar o logon único do Harmony (SSO) 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á habilitado, 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 relance o Design Studio.

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

Sintoma: Um administrador é 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 bloqueado na conta do 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 para atualizar ou desativar 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, portanto 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 estiverem em fusos horários diferentes, o horário de expiração efetivo será diferente 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 você 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 diretamente à sua lista de Bypass de SSO.
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 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 Política de token 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 em segundo plano ou de uma atualização de token agendada 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 autenticadas novamente 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 para o 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 para a 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. 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 mover 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. 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, juntamente 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 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 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. Os 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 prazo.
Resolução:
- Confirme que o projeto foi implantado desde que o agendamento foi atribuído à operação.
- Confirme que o agendamento está habilitado. Os 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 especial à 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 Gerenciador de Tarefas. 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 propriedade Run type da ferramenta Invoke Operation definida como Asynchronously, ou RunOperation chamada 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.
Resolução:
- Se a pai depende de valores que a filha produz, invoque a filha de forma síncrona (a propriedade Run type da ferramenta Invoke Operation definida 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.
Relacionado: Para o comportamento equivalente em operações multi-thread em chunks, consulte Atualizações de variáveis perdidas em operações multi-thread em chunks.

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 de suporte está excedendo o timeout do gateway de API, ou a solicitação não pode ser atribuída a um agente disponível. Consulte HTTP 504 Gateway Timeout para obter as causas completas e a 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 privada, o gateway não consegue abrir seu arquivo de payload ou resposta hospedado e retorna um 507 mesmo quando há espaço em disco disponível. Isso geralmente indica um problema de registro de domínio privado ou configuração do gateway.
Resolução:
- Confirme que o agente ou host do gateway tem espaço em disco livre suficiente.
- Se o espaço em disco é suficiente e a API é servida através de um gateway de API privada, consulte Gateway privado retorna HTTP 507 ou "No such file or directory" para a causa e resolução.

502 Bad Gateway

Sintoma: Uma operação que usa Jitterbit Message Queue (JBMQ) falha com:
```
502 Bad Gateway
```
O servidor retornou uma resposta inválida ou incompleta.
Possível causa: O serviço JBMQ não retornou uma resposta completa à solicitação, produzindo um 502. Esse erro é geralmente transitório e pode não ser reproduzível.
Resolução:
1. Tente 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 dos arquivos temporários, ou o disco está cheio.
- Em um grupo de agentes na nuvem, a causa está no lado do agente gerenciado pela Jitterbit, não no seu projeto ou configuração.
Resolução:
- Para agentes privados, confirme que a conta de serviço do agente possui permissões suficientes no caminho dos arquivos temporários (/tmp ou TemporaryFiles), e verifique se o host do agente possui espaço em disco 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, 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 TLS mútuo (certificado do cliente) de saída 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 do 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 vários componentes do mesmo tipo com nomes idênticos. O Studio impede a criação de nomes duplicados ao configurar componentes diretamente na interface, mas uma importação completa do projeto não aplica essa verificação.
Resolução:
1. No painel do projeto, identifique os componentes inválidos, mostrados em itálico vermelho com um ícone de erro .
2. Clique no ícone de erro para visualizar o nome duplicado específico que causa 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 agentes 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 completa do projeto 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. Os 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 agentes privados que tenha o conector necessário instalado.
- Se o projeto deve ser executado em agentes na nuvem, substitua as atividades do conector exclusivo de agente privado por conectores compatíveis com a nuvem (como HTTP v2 para APIs REST ou o conector de Banco de Dados com um endpoint acessível na nuvem) antes de importar.

Nó de loop de destino mapeado para vários nós de loop de origem

Sintoma: Uma transformação é inválida ou falha ao ser implantada com:

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

Possível causa: Um nó de loop de destino possui mapeamentos de campo que fazem referência a dois ou mais nós de loop de origem diferentes. Cada nó de loop de destino pode iterar apenas sobre um único nó de loop de origem.
Resolução:
1. Abra a transformação e identifique o nó de loop de destino indicado 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: As 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 Substituir os caracteres &, <, >, ' e " dentro da seção CDATA, incluindo os delimitadores CDATA (<![CDATA[ ... ]]>), pelos 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 do HTTP v2 com Obter conteúdo de resposta em string base64 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 o processamento JSON legado (o padrão para projetos criados antes do lançamento Harmony 11.48), isso pode fazer com que o endpoint retorne erros porque os nomes 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. 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 12.8 e 12.9 do agente, a detecção automática de codificação de caracteres amostra apenas o início da resposta para determinar sua codificação. Se essa amostra contiver apenas caracteres ASCII, a resposta é detectada como Latin-1 (ISO-8859-1) em vez de UTF-8, corrompendo qualquer caractere multibyte que apareça além da porção amostrada.
Resolução: Atualize para a versão 12.10 ou posterior do agente, 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 em tempo de execução:
```
Failed to initialize transformation "<transformation name>". Failed to expand the (source|target) tree for the path: <path to substitution head node>.
```
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 tempo de execução com um erro como:

Falha ao inicializar a transformação "<transformation name>". Falha ao expandir a árvore de destino para o caminho: <path to node>. O nó: <node name> não pode ser criado.

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, em seguida, 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, em seguida, 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 você precisar 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.

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 o branch errado é executado:
```
$value = "test";
If($value == 0, WriteToOperationLog("equal"), WriteToOperationLog("not equal"));
// logs "equal", even though "test" is not 0
```
Causa: Quando os dois operandos 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 contra um valor específico, compare-a com um literal de string (por exemplo, $value == "0" ou $value == "") em vez de um número. Se um valor 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 do prefixo de namespace:
- Antes de 10.25: Esquemas XML espelhados usavam o prefixo de namespace padrão xsi.
- 10.25 e posterior: Esquemas XML espelhados usam o prefixo de namespace qualificado ns. Campos não mapeados não são exibidos no esquema.
Resolução: A partir da versão 10.27, importar um projeto cujos esquemas XML espelhados foram criados antes de 10.25 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. Por outro lado, um valor como "1string" produziria 1, já que o dígito inicial é mantido.
Resolução:
1. Verifique a definição do esquema para o campo de destino afetado e confirme se seu tipo de 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: Os campos de destino aparecem em branco na saída da operação mesmo que os dados de origem contenham valores. Este problema ocorre especificamente ao usar um esquema de origem 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 origem simples.
Resolução:
1. Adicione uma etapa de script no início da operação que desabilite as transformações de streaming definindo jitterbit.transformation.auto_streaming como false:
```
$jitterbit.transformation.auto_streaming = false;
```
2. 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, há 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á faltando.
- 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 gravar um arquivo em um destino que já contém um arquivo com o mesmo nome.
Possível causa: FlushFile e FlushAllFiles (e por extensão ArchiveFile) lançam um erro se um arquivo com o nome de destino já existe no local de destino.
Resolução:
- Adicione uma chamada DeleteFile ou DeleteFiles antes da operação de gravação para remover o arquivo existente.
- Alternativamente, use um nome de arquivo dinâmico que inclua um timestamp ou identificador ú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 excluído 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 por meio de uma API, pode aparecer como um Proxy Error [502] enganoso retornado ao chamador da API.
Possível causa: Se o argumento path passado para GetJSONString for inválido ou não corresponder a nenhum dado, a função interrompe o fluxo de execução imediatamente e retorna um erro, o que pode fazer com que todo o script seja abortado.
Resolução:
- Valide o caminho JSON antes de passá-lo para GetJSONString, ou (na versão do agente 11.59 / 12.3 ou posterior) use GetJSONStringEx, que retorna um valor personalizável em vez de interromper a execução quando o caminho é inválido ou não encontrado.
- Registre 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 é desmapiado. 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 desmapiava 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, portanto 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 a mudança de drivers não for possível, recupere 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 se 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 de AESDecryption para ativar a compatibilidade com OpenSSL 3.
- Como alternativa, substitua AESDecryption por AESDecryptionEx, que oferece suporte a OpenSSL 3 por padrão em versões de agente 11.42 ou posterior.

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

Sintoma: Quando uma operação é executada com divisão em lotes ativada 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 é preencher 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 lote é 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 preparo e consolide os resultados em uma operação subsequente com um único thread. Para um exemplo prático do padrão de preparo, consulte Escopo de variáveis com divisão em lotes.
- De forma mais geral, não confie em atualizações de variáveis globais ou de projeto de operações com divisão em lotes 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 divisão em lotes que seja executada antes ou depois da transformação com divisão em lotes. Para detalhes sobre o comportamento de divisão em lotes com variáveis, consulte Usar variáveis com divisão em lotes.

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.
- Este comportamento é específico para saída hierárquica. Quando o esquema de saída é simples, a normalização não é executada e todos os registros são gravados.
- O mecanismo de transformação também remove espaços em branco à esquerda e à direita dos valores de campo CSV por padrão. Registros que diferem apenas por espaços à esquerda ou à direita tornam-se idênticos após a remoção e estão sujeitos à mesma desduplicação.
Resolução:
- Ative o chunking nas opções de operação. O chunking processa registros em lotes, o que ignora a normalização e preserva todos os registros, incluindo duplicados.
- Use um esquema de saída simples na transformação em vez de um hierárquico. A normalização não se aplica à saída simples, portanto todos os registros são preservados.
- Desabilite a normalização 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 cuidadosamente.
- 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)
```

Saída de transformação JSON omite campos `null` e string vazio

Sintoma: Uma transformação JSON remove campos cujo valor é null ou uma string vazia ("") da carga de saída, mesmo que esses campos sejam mapeados explicitamente. O sistema de destino recebe uma carga 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, 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 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, nenhum contexto de tempo de execução existe 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.
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 correção mais simples para um valor configurado estaticamente. 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 funciona 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, antes da linha que a utiliza. Como uma variável global obtém seu valor da execução do script em vez da injeção em tempo de execução, 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 aborda tanto o método de pill de variável quanto o método de sintaxe inline para campos que não mostram um pill).

`IsNull` retorna false para strings vazias de dados de origem JSON

Sintoma: IsNull retorna false para um campo mapeado de uma origem JSON, mesmo quando o campo parece não ter valor. A lógica downstream que depende da verificação de 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 retorna corretamente 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 deve 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, ele 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, atribua-a 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 avalia para 5.6843418860808e-14 em vez de 0.
Possível causa: O Jitterbit Script armazena números como valores de ponto flutuante. A maioria das frações decimais não pode ser representada exatamente em ponto flutuante binário, 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 altera como o valor é armazenado ou calculado.
Resolução:
- Aplique Round ao resultado: Use Round com o número de casas decimais necessárias para o cálculo:
```
$a = Round(Double(12.01) - Double(12.00), 2); // 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 do agente 12.8 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 agentes versão 12.8 e posterior, essas funções tratam meia-noite (00:00:00) como um valor de hora válido e o preservam no valor retornado, da mesma forma que qualquer outra hora. Anteriormente, um valor de exatamente meia-noite era truncado para uma string 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 decorrer, ou expira após 30 minutos independentemente do que foi definido em WriteCache.
Possível causa: Cada chamada para ReadCache redefine a expiração do item em cache para 30 minutos (1800 segundos), a menos que o parâmetro expirationSeconds seja explicitamente fornecido. A expiração de WriteCache se aplica apenas 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:

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

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

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

### `RunXSLT` falha com "XML version must be 1.0 or 1.1" {: #runxslt-html-output}

-   **Sintoma:** [`RunXSLT`](/pt/integration-studio/design/functions/xml-functions/#xmlfunctions-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 este erro. A mensagem de erro refere-se à 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` completamente (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](/pt/agent/plugins/xsl-transform/) descontinuado usa o processador XSLT Saxon e suporta formatos de saída não XML, incluindo HTML. Consulte [Plugins disponíveis](/pt/agent/plugins/plugins-available/) para detalhes de instalação.

### `SelectSingleNode` retorna o nó errado quando usado com um elemento de array `SelectNodes` {: #selectsinglenode-wrong-node}

-   **Sintoma:** [`SelectSingleNode`](/pt/integration-studio/design/functions/xml-functions/#xmlfunctions-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`](/pt/integration-studio/design/functions/xml-functions/#xmlfunctions-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 {: #hextobinary-log-display}

-   **Sintoma:** [`HexToBinary`](/pt/integration-studio/design/functions/conversion-functions/#conversionfunctions-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`](/pt/integration-studio/design/functions/logging-and-error-functions/#logginganderrorfunctions-writetooperationlog) não consegue gerar 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`](/pt/integration-studio/design/functions/file-functions/#filefunctions-writefile). Por exemplo:

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

### `SortArray` classifica nomes de arquivo lexicograficamente, não cronologicamente {: #sortarray-lexicographic}

-   **Sintoma:** [`SortArray`](/pt/integration-studio/design/functions/dictionary-and-array-functions/) 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 ordenação de string (lexicográfica). Para um nome de arquivo como `ordall_DDMMYYHHMMSS.txt`, a parte do dia precede a parte do ano na string, portanto uma ordenação alfabética não corresponde a uma ordenação baseada em data.
-   **Resolução:**
    -   Se você controlar a convenção de nomenclatura de arquivo, mude para um formato que seja ordenado corretamente quando classificado alfabeticamente, como `YYYY-MM-DD_HHMMSS_filename.txt`. Esta é a solução mais simples e confiável.
    -   Se o formato do nome de arquivo não puder mudar, analise a porção de data de cada nome de arquivo em uma chave ordenável (por exemplo, `YYYYMMDDHHMMSS`) e ordene pela chave analisada em vez do nome de arquivo bruto.

### `URLEncode` não codifica certos caracteres "seguros" ou multibyte {: #urlencode-safe-characters}

-   **Sintoma:** Um valor passado por [`URLEncode`](/pt/integration-studio/design/functions/string-functions/#stringfunctions-urlencode) é enviado para o destino com alguns caracteres deixados sem codificação, fazendo com que o sistema receptor rejeite a solicitação ou interprete mal o valor. Isso afeta comumente credenciais ou valores de consulta que contêm caracteres como `$`, `+` ou `!`.
-   **Possíveis causas:**
    -   `URLEncode` segue [RFC 1738](https://tools.ietf.org/html/rfc1738) e trata esses caracteres como "seguros", portanto nunca os codifica: `$ - _ . + ! * ' ( ) ,`. Um destino que espera que esses caracteres sejam codificados em percentual recebe o caractere bruto em vez disso.
    -   O suporte a caracteres multibyte em `URLEncode` 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
        <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" {: #js-tomcat-failed}

-   **Sintoma:** Uma etapa [JavaScript](/pt/integration-studio/design/scripts/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, reduzindo 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 puder 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](#script-loop-iteration-limit-exceeded)) não aumenta o teto de recursão, que não é exposto como uma configuração configurável.

### JavaScript: Alterações de variável global perdidas em falha de script {: #js-global-var-lost}

-   **Sintoma:** Um script [JavaScript](/pt/integration-studio/design/scripts/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 a sintaxe `$variable` com `Jitterbit.SetVar`/`Jitterbit.GetVar` para a mesma variável dentro de um script JavaScript pode causar comportamento de tempo de execução imprevisível.
-   **Resolução:**
    -   Estruture scripts JavaScript para que todas as atribuições de variáveis globais ocorram após a lógica que pode falhar, ou use tratamento de erros para evitar falhas no meio do script.
    -   Para qualquer variável em um script JavaScript, use a sintaxe `$variable` ou `Jitterbit.SetVar`/`Jitterbit.GetVar`, nunca ambas. Escolha uma e use-a consistentemente em todo o script.
    -   Para confirmar quais variáveis estão sendo definidas, adicione chamadas [`WriteToOperationLog`](/pt/integration-studio/design/functions/logging-and-error-functions/#logginganderrorfunctions-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 {: #getvar-null-project-variables}

-   **Sintoma:** Chamar `Jitterbit.GetVar` em uma variável de projeto definida pelo usuário em uma etapa de script [JavaScript](/pt/integration-studio/design/scripts/javascript/) retorna `null` em vez do valor da variável, sem mensagem de erro.
-   **Possível causa:** `Jitterbit.GetVar` e `Jitterbit.SetVar` são destinados a variáveis do sistema Jitterbit (por exemplo, [`jitterbit.operation.name`](/pt/integration-studio/design/variables/jitterbit/operation-jitterbit-variables/#jitterbitoperationname)) 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 um 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 em 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 um ponto. Reserve `GetVar` e `SetVar` para variáveis do sistema Jitterbit e para variáveis cujos nomes contêm um ponto (por exemplo, `$hello.world`), que a notação de ponto do JavaScript não 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áveis globais perdidas em caso de falha de script](/pt/integration-studio/troubleshooting/operation/#js-global-var-lost).

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

### Um arquivo de schema substitui o projeto inteiro ao ser enviado {: #schema-upload-project-wide}

-   **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](/pt/integration-studio/design/transformations/choose-schema-source/#update-transformation-defined-schemas)). 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 não sobrescreva o arquivo compartilhado.

### A implantação do modelo de processo do Marketplace falha devido a incompatibilidade de schema {: #marketplace-schema-mismatch}

-   **Sintoma:** Um projeto importado de um template de processo do [Marketplace](/pt/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 para 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 <span class="icon-refresh"></span> (ou na palavra **Atualizar**) para regenerar o schema do seu endpoint conectado.
    2.  Se o schema ainda não corresponder após a atualização, limpe o schema existente e espelhe-o novamente a partir de um arquivo de 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 {: #studio-slow-large-projects}

-   **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](/pt/integration-studio/design/operations/settings/actions/) 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`](/pt/integration-studio/design/functions/general-functions/#generalfunctions-runscript).

### Amazon Bedrock: erro de modelo "on-demand throughput isn't supported" {: #bedrock-region-prefix}

-   **Sintoma:** Uma atividade do [Amazon Bedrock](/pt/integration-studio/design/connectors/amazon-bedrock/) falha com:

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

-   **Possível causa:** Alguns modelos estão disponíveis apenas em regiões específicas e requerem um prefixo de região no ID do modelo.
-   **Resolução:**
    1.  Adicione o prefixo de região ao ID do modelo. Por exemplo, `anthropic.claude-3-5-haiku-20241022-v1:0` se torna `us-anthropic.claude-3-5-haiku-20241022-v1:0`.
    2.  Digite o ID do modelo com prefixo usando a opção **Enter model identifier** na configuração da atividade.

### Cloud Datastore: a atividade Delete Items relata sucesso, mas não exclui o registro {: #cloud-datastore-delete-key}

-   **Sintoma:** Uma atividade **Delete Items** do [Cloud Datastore](/pt/integration-studio/design/connectors/cloud-datastore/) relata sucesso no log de operação, mas o registro de destino ainda existe quando consultado posteriormente.
-   **Possível causa:** **Delete Items** identifica registros pela **Key** (ou **Alternative Key**) do armazenamento, fornecida no array `keys` ou `ids` da solicitação. (Ambos os arrays aceitam valores de chave ou chave alternativa.) Se o ID interno do registro for fornecido em vez de seu valor de chave, nenhum item corresponde e a atividade relata sucesso sem deletar nada.
-   **Resolução:**
    -   Na transformação que prepara a solicitação [Delete Items](/pt/integration-studio/design/connectors/cloud-datastore/delete-items-activity/), mapeie a **Key** (ou **Alternative Key**) do armazenamento, não o ID do registro interno.
    -   Ao encadear a partir de uma atividade **Query Items**, mapeie o valor `key` da resposta da consulta para a solicitação de exclusão.

### Coupa: autenticação por chave de API retorna 403 Forbidden {: #coupa-api-keys-deprecated}

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

### Banco de dados (JDBC): `DBLookup` ou `DBExecute` falha com erro de decodificação Base64 {: #jdbc-base64-decoding}

-   **Sintoma:** Uma função [`DBLookup`](/pt/integration-studio/design/functions/database-functions/#databasefunctions-dblookup) ou [`DBExecute`](/pt/integration-studio/design/functions/database-functions/#databasefunctions-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`](/pt/integration-studio/design/functions/conversion-functions/#conversionfunctions-hextostring). Por exemplo, no PostgreSQL: `SELECT encode(<column>, 'hex')`. Use o equivalente SQL `decode(...,'hex')` com [`StringToHex`](/pt/integration-studio/design/functions/conversion-functions/#conversionfunctions-stringtohex) ao escrever o valor de volta no banco de dados.

### Banco de dados (ODBC): caracteres multibyte não são tratados corretamente {: #db-odbc-multibyte}

-   **Sintoma:** Ao ler ou escrever em um banco de dados por meio do [conector Database](/pt/integration-studio/design/connectors/database/) usando um driver ODBC, caracteres multibyte ou não-ASCII (por exemplo, caracteres acentuados ou não-latinos) não são tratados corretamente.
-   **Possível causa:** O suporte a caracteres multibyte para o conector Database por um driver ODBC não está habilitado por padrão. A variável Jitterbit [`jitterbit.scripting.db.multibyte.enable`](/pt/integration-studio/design/variables/jitterbit/scripting-jitterbit-variables/#jitterbitscriptingdbmultibyteenable) deve ser definida como `true`. Este suporte está disponível na versão do agente 12.6 e posterior, e não é necessário ao usar um driver JDBC.
-   **Resolução:**
    1.  Confirme que o agente é versão 12.6 ou posterior.
    2.  Defina a variável `jitterbit.scripting.db.multibyte.enable` como `true` antes da operação do banco de dados ser executada. Por exemplo, em uma etapa de script:

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

### Banco de dados: conexão bloqueada pela política de segurança {: #db-security-policy-block}

-   **Sintoma:** Um teste de conexão do [conector de Banco de dados](/pt/integration-studio/design/connectors/database/) falha com:

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

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

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

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

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

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

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

### Banco de dados: `DBLookup` ou `DBExecute` falha com "No suitable driver found" ao testar um script {: #db-test-script-variables}

-   **Sintoma:** Testar um script (usando **Run test**) que chama [`DBLookup`](/pt/integration-studio/design/functions/database-functions/#databasefunctions-dblookup) ou [`DBExecute`](/pt/integration-studio/design/functions/database-functions/#databasefunctions-dbexecute) falha com:

    ```
    No suitable driver found for [...]
    ```

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

-   **Possível causa:** A [conexão de Banco de dados](/pt/integration-studio/design/connectors/database/database-connection/) usada pela função tem seu campo **Login**, **Password** ou **Connection String** definido como uma variável global ou de projeto. Um teste de script executa apenas o script testado, portanto a variável ainda não recebeu seu valor de tempo de execução quando a função resolve a conexão. Diferentemente de uma variável referenciada em um campo configurado da própria atividade, isso não é coberto pelo valor padrão de uma variável; uma função de banco de dados não lê o valor padrão ao resolver uma conexão.

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

### Banco de dados: erros de comprimento de campo em Insert, Update ou Upsert {: #db-truncation-errors}

-   **Sintoma:** Uma atividade de **Insert**, **Update** ou **Upsert** do [Banco de dados](/pt/integration-studio/design/connectors/database/) falha com um status de operação **Error** quando um valor de origem mapeado é maior do que o permitido pela coluna de destino. O log de operação contém um dos seguintes:

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

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

-   **Possível causa:** Por padrão, se um valor de origem mapeado exceder o comprimento definido da coluna de destino, a atividade rejeita a linha e relata um status de **Erro** em vez de truncar o valor.
-   **Resolução:**
    1.  Na configuração da atividade **Insert**, **Update** ou **Upsert** do Banco de Dados, ative **Permitir truncamento de campos de caracteres para evitar erros de comprimento de campo**. Com essa opção ativada, valores que excedem o comprimento do campo de destino são truncados e a operação relata um status de **Sucesso com Informações** em vez de um status de **Erro**.
    2.  Se o truncamento não for aceitável, corte ou transforme o campo de origem no mapeamento de transformação para que os valores nunca excedam o comprimento da coluna de destino, ou amplie a coluna de destino no lado do banco de dados.
    3.  Reimplante e execute novamente a operação.

### Banco de dados: JAR do driver JDBC sobrescrito em atualizações de agente {: #jdbc-jar-overwritten}

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

### Banco de dados: caracteres especiais em nomes de coluna causam falhas de consulta {: #column-name-special-chars}

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

### Banco de dados: instrução SQL excede o limite de 2.000 caracteres {: #sql-statement-length-limit}

-   **Sintoma:** Uma atividade **Query** do Banco de Dados falha ou é truncada quando a instrução SQL configurada é muito longa.
-   **Possível causa:** O campo de instrução SQL em uma atividade [Query](/pt/integration-studio/design/connectors/database/database-query-activity/) do Banco de Dados aceita um máximo de 2.000 caracteres.
-   **Resolução:**
    1.  Crie uma visualização de banco de dados que encapsule a lógica de consulta complexa.
    2.  Referencie o nome da visualização na atividade **Query** em vez da instrução SQL completa.

### IBM DB2 no iSeries: falha na conexão JDBC {: #db2-iseries-jdbc}

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

### IBM DB2: configuração do driver JDBC JCC (JAR e arquivo de licença descontinuados) {: #db2-jcc-driver}

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

### Kerberos: "Could not initialize class KerbAuthentication" {: #kerberos-kerb-init}

-   **Sintoma:** uma conexão de [Banco de Dados](/pt/integration-studio/design/connectors/database/) 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`:

        ```sh
        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 {: #kerberos-jgss-errors}

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

### Microsoft Excel: "Operation must use an updateable query" {: #excel-updateable-query}

-   **Sintoma:** uma atividade de [Inserção](/pt/integration-studio/design/connectors/database/database-insert-activity/) ou [Atualização](/pt/integration-studio/design/connectors/database/database-update-activity/) de Banco de Dados direcionada a um arquivo do Microsoft Excel (via ODBC) falha com:

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

-   **Possível causa:** o driver ODBC do Excel abre o arquivo do Excel em modo somente leitura por padrão, a menos que a string de conexão defina explicitamente o modo de leitura/gravação.
-   **Resolução:** no campo **Connection String** da conexão de Banco de Dados (inserido em **Optional Settings** com **Use Connection String** selecionado), acrescente `ReadOnly=0;` ao final da string de conexão para abrir o arquivo do Excel em modo de leitura/gravação.

### MySQL: acesso negado apesar de credenciais corretas {: #mysql-access-denied}

-   **Sintoma:** A conexão com um banco de dados MySQL usando o [conector de banco de dados](/pt/integration-studio/design/connectors/database/) falha com:

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

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

-   **Possível causa:** O MySQL pode conceder permissões diferentes com base no endereço IP do cliente. Uma conta de usuário pode ter os privilégios necessários de endereços IP específicos, mas não do endereço IP do agente privado.
-   **Resolução:**
    -   No MySQL, verifique se a conta de usuário possui as concessões necessárias para conexões do endereço IP do agente privado. A sintaxe exata de concessão varia conforme a versão do MySQL (consulte a documentação do MySQL ou entre em contato com o administrador do MySQL), mas geralmente assume a forma:

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

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

### MySQL: Enable Batch não melhora o desempenho de Insert ou Update {: #mysql-enable-batch-no-improvement}

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

### MySQL: driver ODBC não aparece na lista suspensa do Studio {: #mysql-odbc-driver-not-listed}

-   **Sintoma:** Ao configurar uma conexão de [banco de dados](/pt/integration-studio/design/connectors/database/) 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](/pt/integration-studio/design/connectors/database/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 {: #postgres-client-encoding}

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

### PostgreSQL: Use o driver fornecido pelo Jitterbit no Linux {: #postgres-linux-driver}

-   **Sintoma:** Operações usando o [conector de Banco de Dados](/pt/integration-studio/design/connectors/database/) para conectar ao PostgreSQL a partir de um agente privado no Linux falham ou produzem erros, mesmo quando um driver parece estar instalado.
-   **Possível causa:** Muitas distribuições Linux incluem um driver ODBC PostgreSQL empacotado com `unixODBC` que não funciona de forma confiável com o Harmony.
-   **Resolução:** Não use o driver PostgreSQL empacotado pela distribuição. Use o driver ODBC PostgreSQL incluído na instalação do agente Jitterbit.

### SQL Server JDBC: Falha de autenticação integrada do Windows {: #sql-server-jdbc-windows-auth}

-   **Sintoma:** Para agentes privados, uma conexão de [Banco de Dados](/pt/integration-studio/design/connectors/database/) com SQL Server usando um driver JDBC e autenticação integrada do Windows falha com:

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

    Os logs do agente também podem mostrar:

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

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

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

### Autenticação do Windows do SQL Server: Privilégios insuficientes {: #sqlserver-winauth-privileges}

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

### SQL Server: "Não é possível inserir valor explícito para coluna de identidade" ao inserir em uma coluna de identidade {: #identity-insert-unmapped}

-   **Sintoma:** Uma operação do [conector de Banco de Dados](/pt/integration-studio/design/connectors/database/) que escreve em uma tabela do SQL Server com uma coluna de identidade falha com:

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

-   **Possível causa:** A coluna de identidade está incluída na instrução INSERT que o conector de Banco de Dados gera para o destino. O SQL Server rejeita um INSERT que referencia uma coluna de identidade em sua lista de colunas (com um valor explícito ou nulo) enquanto `IDENTITY_INSERT` está definido como `OFF`. Mapear o campo para um valor nulo não o exclui: um campo de destino é omitido do INSERT apenas quando é mapeado com a função [`Unmap`](/pt/integration-studio/design/functions/database-functions/#databasefunctions-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`](/pt/integration-studio/design/functions/database-functions/#databasefunctions-unmap). Para excluir a coluna apenas quando a origem não fornece um valor, use um mapeamento condicional:

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

Quando a condição é falsa, `Unmap` remove a coluna do INSERT e o SQL Server atribui o próximo valor de identidade. (Fornecer um valor explícito na ramificação verdadeira ainda requer que `IDENTITY_INSERT` esteja `ON`; consulte a próxima opção.)

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

    ```sql
    SET IDENTITY_INSERT <table> ON;
    ```

    ```sql
    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: Conexão falha com erro de caminho de certificado PKIX {: #sql-server-pkix}

-   **Sintoma:** Uma conexão de [Banco de Dados](/pt/integration-studio/design/connectors/database/) com SQL Server falha com:

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

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

-   **Possível causa:** As versões atuais do driver **SQL Server MS JDBC** solicitam uma conexão criptografada por padrão e validam o certificado que o servidor de banco de dados apresenta. A conexão falha quando esse certificado não pode ser rastreado até uma autoridade de certificação (CA) que o agente já confia, como um certificado autoassinado, um certificado emitido internamente ou o certificado CA do Amazon RDS que uma instância do [Amazon RDS para SQL Server](https://aws.amazon.com/rds/sqlserver/) apresenta. Trata-se de uma falha de confiança de certificado e não de criptografia, portanto um banco de dados pode ter criptografia ativada e um certificado válido instalado e ainda assim falhar. A versão 12.8 do agente atualizou o driver incluído para uma versão que solicita criptografia por padrão, portanto uma conexão configurada antes dessa atualização pode falhar depois.

-   **Resolução:** Digite `encrypt=false;` no campo **Parâmetros de Cadeia de Conexão Adicionais** em **Configurações Opcionais** da [conexão de Banco de Dados](/pt/integration-studio/design/connectors/database/database-connection/), 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](/pt/integration-studio/design/connectors/database/microsoft/#connection-encryption-and-server-certificates).

    !!! caution "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 vários campos de destinatário {: #email-duplicate-recipient}

-   **Sintoma:** Uma atividade **Enviar Email** do [Email](/pt/integration-studio/design/connectors/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 {: #gmail-auth-app-password}

-   **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](https://support.google.com/mail/answer/185833) 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](https://support.google.com/mail/answer/185833) 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: Assinatura S/MIME falha ou é rejeitada por provedores de email em nuvem {: #smime-signing-fails-or-is-rejected-by-cloud-email-providers}

-   **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](https://letsencrypt.org) fornece certificados gratuitos aceitos pelos principais provedores na nuvem.
    2.  Substitua o certificado autoassinado na atividade [Enviar Email](/pt/integration-studio/design/connectors/email/send-email-activity/) do Email pelo certificado emitido pela CA (consulte [Pré-requisitos para criptografia S/MIME](/pt/integration-studio/design/connectors/email/prerequisites-for-s-mime-encryption/)).
    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: Autenticação do Microsoft 365 (ROPC) falha quando MFA está habilitado {: #m365-ropc-mfa}

-   **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](/pt/integration-studio/design/connectors/email/prerequisites-for-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 várias condições de filtro {: #epicor-p21-multiple-filters}

-   **Sintoma:** Uma atividade [Query](/pt/integration-studio/design/connectors/epicor-prophet-21/query-activity/) 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 {: #no-files-match-filter}

-   **Sintoma:** Uma atividade de leitura do [FTP](/pt/integration-studio/design/connectors/ftp/), [Compartilhamento de Arquivo](/pt/integration-studio/design/connectors/file-share/) ou [Armazenamento Local](/pt/integration-studio/design/connectors/local-storage/) falha porque o arquivo que ela espera ler não está mais no caminho de origem:

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

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

-   **Possíveis causas:**
    -   A atividade de processamento já moveu ou deletou o arquivo de origem como parte de seu comportamento **Após Processamento**, então a etapa de arquivo não tem nada para corresponder.
    -   Uma operação filha é iniciada de forma assíncrona e a operação pai tenta ler o arquivo de saída da filha antes que ela termine de escrevê-lo.
    -   Uma atividade **Escrever** do FTP com **Usar Renomeação FTP** habilitada (o padrão) escreve o arquivo com um nome temporário e o renomeia para o nome final após a conclusão. Uma operação de leitura posterior que é executada antes da renomeação ser concluída não encontrará o arquivo.
-   **Resolução:**
    -   Confirme se a etapa anterior já tratou o arquivamento através de suas opções **Após Processamento** integradas (mover, renomear, deletar). Se sim, uma etapa de arquivo separada é redundante e deve ser removida.
    -   Se uma etapa de arquivo separada for necessária, redesenhe a cadeia para que o processamento e o arquivamento ocorram contra a mesma referência de arquivo em memória, em vez de reler da origem. Por exemplo, passe o conteúdo lido através do Armazenamento Temporário para a etapa de arquivo, em vez de reler o caminho de origem.
    -   Se uma etapa posterior ler a saída produzida por uma operação filha, execute a filha de forma síncrona para que sua saída exista antes da leitura. Defina o **Tipo de execução** da ferramenta [Invocar Operação](/pt/integration-studio/design/tools/invoke-operation/#synchronicity) como **Sincronamente**, ou, ao chamar a operação a partir de um script, execute [`RunOperation`](/pt/integration-studio/design/functions/general-functions/#generalfunctions-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](/pt/integration-studio/design/connectors/ftp/ftp-write-activity/). 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 escrita em falha de conexão {: #file-error-folder-connection}

-   **Sintoma:** Após uma atividade de [FTP](/pt/integration-studio/design/connectors/ftp/), [File Share](/pt/integration-studio/design/connectors/file-share/) ou [Local Storage](/pt/integration-studio/design/connectors/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](/pt/integration-studio/design/operations/logs/) 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 {: #ftp-keyword-folder-paths}

-   **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](/pt/integration-studio/design/connectors/ftp/), [File Share](/pt/integration-studio/design/connectors/file-share/) e [Local Storage](/pt/integration-studio/design/connectors/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: Escrever cabeçalhos não produz um arquivo somente de cabeçalho quando a origem não retorna registros {: #write-headers-empty-source}

-   **Sintoma:** Uma atividade de gravação baseada em arquivo com a opção **Write Headers** ativada ([FTP Write](/pt/integration-studio/design/connectors/ftp/ftp-write-activity/), [File Share Write](/pt/integration-studio/design/connectors/file-share/file-share-write-activity/), [Local Storage Write](/pt/integration-studio/design/connectors/local-storage/local-storage-write-activity/) ou [Temporary Storage Write](/pt/integration-studio/design/connectors/temporary-storage/temporary-storage-write-activity/)) 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 {: #sftp-rate-limit}

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

### SFTP "Login negado. Falha de autenticação." ao usar chaves SSH {: #sftp-ssh-key-auth}

-   **Sintoma:** Uma operação SFTP usando autenticação de chave privada SSH falha com `Login denied. Authentication failure.`, mesmo que as mesmas chaves autentiquem com sucesso a partir de um cliente SFTP interativo.

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

-   **Possíveis causas:**
    -   A chave privada está protegida por uma frase-passe, mas a configuração `PrivateKeyPassphrase` está faltando na seção `[SSH]` do [jitterbit.conf](/pt/agent/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](/pt/agent/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 escrever em um servidor SFTP {: #ftp-rename-sftp}

-   **Sintoma:** Uma atividade [FTP](/pt/integration-studio/design/connectors/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](/pt/integration-studio/design/operations/validity/#operationvalidity-archive-pattern).

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

-   **Resolução:**

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

    -   Desmarque a caixa de seleção **Use FTP Rename** na configuração da atividade para que o agent escreva diretamente no caminho de destino em vez de fazer upload para um nome temporário e renomear. Isso evita a etapa de renomeação e resolve ambas as causas.

    -   Para o caso multibyte, use alternativamente um servidor SFTP que suporte renomeação de arquivos cujos nomes contêm caracteres multibyte.

### SFTP: Acrescentar ao arquivo não é suportado {: #sftp-append-not-supported}

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

### FTP: Nomes de arquivo contendo `#` não são tratados corretamente {: #file-hash-filename}

-   **Sintoma:** Uma atividade do conector [FTP](/pt/integration-studio/design/connectors/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`](/pt/integration-studio/design/variables/jitterbit/source-jitterbit-variables/#jitterbitsourceftpencode_url) como `true` em um script de transformação para nomes de arquivo ou pasta de origem, e [`jitterbit.target.ftp.encode_url`](/pt/integration-studio/design/variables/jitterbit/target-jitterbit-variables/#jitterbittargetftpencode_url) como `true` para arquivos escritos no destino.

### Compartilhamento de Arquivos: Caminhos UNC com nomes de servidor falham em agentes na nuvem {: #file-share-unc-cloud}

-   **Sintoma:** Conexões do [File Share](/pt/integration-studio/design/connectors/file-share/) que usam caminhos UNC (por exemplo, `\\server\share`) falham ao conectar quando a operação é executada em um agente na nuvem.
-   **Possível causa:** Agentes na nuvem conseguem resolver caminhos UNC usando um endereço IP público, mas não conseguem resolver nomes de host de servidor em caminhos UNC.
-   **Resolução:**
    -   Substitua o nome do servidor no caminho UNC pelo endereço IP público do servidor (por exemplo, `\\192.0.2.1\share`).
    -   Se a resolução de nome de servidor em caminhos UNC for necessária, use um agente privado.

### Compartilhamento de Arquivos: Arquivos maiores que 2 GB podem falhar na recuperação {: #file-share-2gb}

-   **Sintoma:** Uma atividade **Ler** de [Compartilhamento de Arquivos](/pt/integration-studio/design/connectors/file-share/) pode falhar ao recuperar arquivos individuais maiores que 2 GB. Arquivos menores são recuperados sem problemas.
-   **Possível causa:** O conector de Compartilhamento de Arquivos tem uma limitação conhecida com arquivos individuais maiores que 2 GB.
-   **Resolução:** Nenhuma opção de configuração remove esse limite. Como alternativa, divida o arquivo em segmentos menores na origem para que cada arquivo tenha menos de 2 GB antes que a atividade **Ler** do Compartilhamento de Arquivos o recupere.

### Armazenamento Local: Não disponível em agentes na nuvem {: #local-storage-cloud}

-   **Sintoma:** Uma operação usando um conector de [Armazenamento Local](/pt/integration-studio/design/connectors/local-storage/) falha quando executada em um agente na nuvem.
-   **Possível causa:** O Armazenamento Local acessa o sistema de arquivos da máquina onde o agente está instalado. Agentes na nuvem são executados em um ambiente hospedado e não expõem um sistema de arquivos local para esse fim.
-   **Resolução:**
    -   Use agentes privados para qualquer operação que exija o conector de Armazenamento Local. O Armazenamento Local é desabilitado em agentes privados por padrão, então também ative-o no arquivo de configuração do agente privado (consulte [Ativar local de arquivo local](/pt/agent/jitterbit-conf/#settings)).
    -   Para fluxos de trabalho de agentes na nuvem, substitua o Armazenamento Local por [Armazenamento Temporário](/pt/integration-studio/design/connectors/temporary-storage/) ou um conector de armazenamento externo (Compartilhamento de Arquivos, FTP ou Cloud Datastore).

### Armazenamento Temporário: Arquivos ausentes quando lidos por uma operação posterior {: #temp-storage-missing}

-   **Sintoma:** Arquivos do [Armazenamento Temporário](/pt/integration-studio/design/connectors/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 Armazenamento Temporário após 24 horas por padrão.
    -   Cada agente em um grupo de agentes tem seu próprio Armazenamento Temporário local. Operações na mesma cadeia de operações têm garantia de execução no mesmo agente, mas uma operação posterior que não esteja na mesma cadeia pode ser despachada para um agente diferente e acessar uma instância diferente do Armazenamento Temporário, portanto não encontra o arquivo, independentemente da janela de 24 horas. Consulte [Notas importantes](/pt/integration-studio/design/connectors/temporary-storage/#temporarystorage-important-notes).
-   **Resolução:**
    -   Vincule operações que devem compartilhar arquivos do Armazenamento Temporário na mesma [cadeia de operações](/pt/integration-studio/design/workflows/creation-and-design/#operation-chains) usando [ações de operação](/pt/integration-studio/design/operations/settings/actions/), onde o comportamento do Armazenamento Temporário é consistente e confiável.
    -   Para agentes privados, a frequência de limpeza pode ser ajustada na seção `[FileCleanup]` de `jitterbit.conf`. Consulte [`[FileCleanup]`](/pt/agent/jitterbit-conf/#filecleanup).
    -   Se os arquivos não puderem ser consumidos na mesma cadeia ou precisarem persistir por mais de 24 horas, use um conector de armazenamento persistente acessível a todos os agentes (como Compartilhamento de Arquivos, FTP ou Cloud Datastore) em vez do Armazenamento Temporário.

### Armazenamento Temporário: Caracteres restritos em caminhos de arquivo {: #temp-storage-restricted-chars}

-   **Sintoma:** Uma atividade de [Leitura](/pt/integration-studio/design/connectors/temporary-storage/temporary-storage-read-activity/) ou [Gravação](/pt/integration-studio/design/connectors/temporary-storage/temporary-storage-write-activity/) do Armazenamento Temporário falha quando o caminho do arquivo contém certos caracteres especiais.
-   **Possível causa:** Os seguintes caracteres não são suportados em caminhos de arquivo do Armazenamento Temporário: `~`, `%`, `$`, `"`, `<`, `>`, `:`, `?`
-   **Resolução:**
    -   Remova ou substitua os caracteres não suportados no caminho do arquivo. Os seguintes caracteres são suportados: `!`, `@`, `#`, `^`, `&`, `*`, `(`, `)`, `[`, `]`, `'`, `;`
    -   Tanto `/` quanto `\` são aceitos como separadores de caminho.

### Armazenamento Temporário: Limite de tamanho de arquivo de 50 GB em agentes na nuvem {: #temp-storage-size-limit}

-   **Sintoma:** uma atividade de [Gravação](/pt/integration-studio/design/connectors/temporary-storage/temporary-storage-write-activity/) 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` {: #url-encoding}

-   **Sintoma:** Chamadas da API REST usando o conector [HTTP v2](/pt/integration-studio/design/connectors/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](/pt/integration-studio/design/connectors/http-v2/connection/#configure-an-http-v2-connection). 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`](/pt/integration-studio/design/functions/string-functions/#stringfunctions-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 {: #http-v2-status-code-vars}

-   **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](/pt/integration-studio/design/connectors/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](/pt/integration-studio/design/variables/jitterbit/source-jitterbit-variables/) ou [destino](/pt/integration-studio/design/variables/jitterbit/target-jitterbit-variables/). Os dados de resposta, incluindo o código de status HTTP, são retornados através do schema de resposta da atividade.
-   **Resolução:**
    -   Para capturar o código de status usando o schema de resposta padrão, mapeie o campo `statusCode`, que está localizado sob o nó `responseItem/error` da resposta e contém o código de status HTTP (por exemplo, `200`, `403`). Para detalhes sobre a estrutura do schema de resposta, consulte a documentação de configuração da atividade para qualquer atividade [HTTP v2](/pt/integration-studio/design/connectors/http-v2/).
    -   Para capturar o código de status ao usar um schema de resposta personalizado, ative **Incluir Propriedades Adicionais da Resposta HTTP no Schema** na configuração da atividade. Isso envolve o schema com uma estrutura definida pelo Jitterbit que inclui `__jitterbit_api_statuscode__` (o código de status) e `__jitterbit_api_errorbody__` (o corpo da resposta para requisições malsucedidas).
    -   Para que o código de status esteja disponível quando a API retorna uma resposta malsucedida, ative **Ignorar erro de operação em caso de código de status malsucedido** nas configurações opcionais da atividade. Sem essa configuração, a operação falha em respostas malsucedidas antes que os dados de resposta possam ser mapeados.

### HTTP v2: Namespaces XML reescritos ao usar um esquema de solicitação personalizado {: #http-v2-xml-namespaces}

-   **Sintoma:** Uma operação [HTTP v2](/pt/integration-studio/design/connectors/http-v2/) que envia um payload XML para um serviço web SOAP ou XML falha com um erro de servidor (como `500 Internal Server Error`) mesmo que o mesmo payload tenha sucesso quando enviado do Postman ou SoapUI. Ao inspecionar o corpo da requisição recebido pelo destino, observa-se que as declarações de namespace XML foram consolidadas no elemento raiz e os prefixos de namespace originais foram substituídos por genéricos (por exemplo, `soapenv:Envelope` se torna `Envelope xmlns="..."`, e os prefixos de elemento são renumerados como `ns`, `ns1`, `ns2`).
-   **Possível causa:** Quando um schema de requisição personalizado é usado na configuração da atividade HTTP v2, a transformação normaliza o XML por padrão, movendo todas as declarações de namespace para o nó raiz e reatribuindo seus prefixos. Serviços SOAP e outros endpoints XML que validam a consistência de prefixos de namespace rejeitam o payload modificado.
-   **Resolução:**

    -   Na versão do agente 12.8 ou posterior, defina [`jitterbit.target.xml.preserve.namespace.prefix`](/pt/integration-studio/design/variables/jitterbit/target-jitterbit-variables/#jitterbittargetxmlpreservenamespaceprefix) como `true` em uma etapa de script anterior à transformação, para manter os prefixos de namespace do XML de origem em vez de reatribuir genéricos:

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

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

### HTTP v2: Cabeçalho de Autorização duplicado causa erro 400 Bad Request {: #http-v2-duplicate-auth-header}

-   **Sintoma:** operações do [conector HTTP v2](/pt/integration-studio/design/connectors/http-v2/) falham com um erro 400 quando tanto a autenticação no nível de conexão quanto um cabeçalho de solicitação `Authorization` definido manualmente estão configurados na mesma conexão ou atividade.
-   **Possível causa:** quando a autenticação é configurada em uma conexão HTTP v2 (por exemplo, Basic ou OAuth), o conector adiciona automaticamente um cabeçalho `Authorization` a cada solicitação. Adicionar um segundo cabeçalho `Authorization` manualmente resulta em dois cabeçalhos conflitantes, que a maioria dos servidores rejeita com um erro 400.
-   **Resolução:**
    -   Remova qualquer cabeçalho `Authorization` adicionado manualmente dos cabeçalhos de solicitação na configuração da atividade ou conexão.
    -   Use apenas as configurações de autenticação integradas na conexão para lidar com autorização. Não adicione um cabeçalho `Authorization` manual junto com a autenticação configurada.
    -   Se precisar definir o cabeçalho `Authorization` dinamicamente no nível da atividade, defina o tipo de autenticação da conexão como [Sem autenticação](/pt/integration-studio/design/connectors/http-v2/connection-authentication-types/#no-auth) 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 {: #http-v2-header-json-variable}

-   **Sintoma:** uma atividade do [HTTP v2](/pt/integration-studio/design/connectors/http-v2/) que lê um valor de cabeçalho de solicitação de uma [variável de projeto](/pt/integration-studio/design/variables/project/) contendo uma string JSON falha com um erro de parse:

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

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

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

### HTTP e HTTP v2: URL contém múltiplos caracteres `?` {: #http-multiple-query-separators}

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

### HTTP v2: Codificação dupla de URL quando "Codificar URL de solicitação" está ativado {: #http-v2-double-encoding}

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

### HTTP v2: Operação falha quando a URL Base redireciona {: #http-v2-base-url-redirect}

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

### HTTP v2: Variáveis no Caminho da atividade não são resolvidas {: #http-v2-path-variable-not-resolved}

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

### HTTP: Envia `null` como a string `"null"` {: #http-v1-null-serialization}

-   **Sintoma:** Uma atividade [HTTP](/pt/integration-studio/design/connectors/http/) POST ou PUT envia campos mapeados com a função [`Null`](/pt/integration-studio/design/functions/general-functions/#generalfunctions-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](/pt/integration-studio/design/connectors/http-v2/), que serializa `Null` corretamente. A Jitterbit recomenda [converter conexões e atividades HTTP existentes para HTTP v2](/pt/integration-studio/design/connectors/http/convert-to-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 Excluir Entrada falha quando a entrada de destino tem entradas filhas {: #ldap-delete-non-leaf}

-   **Sintoma:** Uma atividade LDAP [Delete Entry](/pt/integration-studio/design/connectors/ldap/delete-entry-activity/) 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`](/pt/integration-studio/design/functions/general-functions/#generalfunctions-runoperation) com a atividade LDAP **Delete Entry** para cada entrada.

### LDAP Pesquisar Entrada: Expressão de filtro diferencia maiúsculas de minúsculas em alguns servidores {: #ldap-filter-case-sensitive}

-   **Sintoma:** Uma atividade LDAP [Search Entry](/pt/integration-studio/design/connectors/ldap/search-entry-activity/) 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 {: #sharepoint-idcrl}

-   **Sintoma:** Operações usando um conector [Microsoft SharePoint Server](/pt/integration-studio/design/connectors/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](/pt/integration-studio/design/connectors/microsoft-sharepoint-server/).

### Microsoft Dynamics 365 Business Central v2: Nomes de tipo incompatíveis com metadados {: #dynamics-bc-odata-type}

-   **Sintoma:** Operações usando o conector [Microsoft Dynamics 365 Business Central v2](/pt/integration-studio/design/connectors/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](/pt/integration-studio/design/connectors/microsoft-dynamics-365-business-central-v2/update-activity/) 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 {: #entra-id-extension-attributes}

-   **Sintoma:** Ao configurar uma atividade [Query](/pt/integration-studio/design/connectors/microsoft-entra-id/query-activity/) 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` {: #entra-id-datetime-type}

-   **Sintoma:** Uma atividade [Update](/pt/integration-studio/design/connectors/microsoft-entra-id/update-activity/) do Microsoft Entra ID falha com:

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

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

### Consulta do Microsoft Entra ID: "Unsupported or invalid query filter clause" em propriedades filtradas {: #entra-id-advanced-query-count}

-   **Sintoma:** Uma atividade [Query](/pt/integration-studio/design/connectors/microsoft-entra-id/query-activity/) do Microsoft Entra ID falha quando uma condição de filtro é aplicada na etapa 3:

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

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

-   **Possível causa:** A filtragem em certas propriedades do Microsoft Entra ID (como `companyName` e `createdDateTime`) usa a capacidade de consulta avançada da API Microsoft Graph, que requer `$count=true` na string de consulta. Sem ela, a API rejeita o filtro mesmo quando a sintaxe está correta. O conector inclui automaticamente o cabeçalho `ConsistencyLevel: eventual` necessário, mas `$count=true` deve ser adicionado separadamente.
-   **Resolução:** Escolha uma das seguintes opções dependendo da aba usada na etapa 3:
    -   **Aba Básica:** Marque a caixa de seleção **Incluir Contagem**. Isso adiciona `$count=true` à consulta automaticamente.
    -   **Aba Avançada:** Acrescente `&$count=true` à string de filtro manualmente. Por exemplo:

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

Para a lista de propriedades que exigem sintaxe de consulta avançada, consulte [Capacidades de consulta avançada em objetos do Microsoft Entra ID](https://learn.microsoft.com/en-us/graph/aad-advanced-queries) na documentação do Microsoft Graph.

### Operações do Microsoft Dynamics AX 2012 falham com "Logon failed" {: #dynamics-ax-2012-domain}

-   **Sintoma:** Operações usando o conector [Microsoft Dynamics AX](/pt/integration-studio/design/connectors/microsoft-dynamics-ax/) contra AX 2012 falham em tempo de execução, mesmo que o teste de conexão seja bem-sucedido no Studio. O log do Serviço REST do Conector Jitterbit Dynamics AX 2012 contém:

    ```
    The server has rejected the client credentials.
    ```
    ```
    The logon attempt failed
    ```

-   **Causa:** O campo **Nome do Domínio** na conexão AX 2012 não está definido com o valor correto. A autenticação AX 2012 requer que o **Nome do Domínio** seja a extensão de nome de domínio DNS (por exemplo, `yourcompany.com`), não um nome de domínio curto ou NetBIOS. Um valor de domínio incorreto faz com que o AX rejeite credenciais válidas com uma falha de logon, mesmo quando o teste de conexão é bem-sucedido.
-   **Resolução:**
    1.  Abra a conexão Dynamics AX 2012 no Studio.
    2.  Defina o campo **Nome do Domínio** para sua extensão de nome de domínio DNS (por exemplo, `yourcompany.com`), não um nome de domínio curto/NetBIOS.
    3.  Confirme que o **Login** é o nome de usuário da conta de serviço AX com os privilégios necessários e reinsira a **Senha** para descartar um valor obsoleto.
    4.  Teste a conexão e execute novamente a operação.

### NetSuite: Erro de URL do data center {: #netsuite-data-center-error}

-   **Sintoma:** Uma [conexão NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-connection/) 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](/pt/integration-studio/design/connectors/netsuite/netsuite-how-tos/use-a-netsuite-account-specific-wsdl-url/).

### NetSuite: `INSUFFICIENT_PERMISSION` apesar do teste de conexão bem-sucedido {: #netsuite-permissions-error}

-   **Sintoma:** Mesmo que o teste de uma [conexão NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-connection/) 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](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4247337262.html).

### NetSuite: Conexão com sandbox falha após atualização do sandbox {: #netsuite-sandbox-tokens}

-   **Sintoma:** Uma [conexão NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-connection/) 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](/pt/integration-studio/design/connectors/netsuite/netsuite-how-tos/gather-values-for-using-netsuite-tba/).

### NetSuite: Campos personalizados não aparecem no schema da atividade {: #netsuite-custom-fields}

-   **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](/pt/integration-studio/design/connectors/netsuite/netsuite-how-tos/expose-custom-fields-in-the-netsuite-connector/) 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 {: #netsuite-custom-segments}

-   **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](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-search-activity/#custom-segments) 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 à permissão de função ausente {: #netsuite-custom-body-fields-permission}

-   **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](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-search-activity/), 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.

### NetSuite: Buscas salvas não aparecem no dropdown {: #netsuite-saved-search-dropdown}

-   **Sintoma:** Ao configurar uma [atividade de Pesquisa do NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-search-activity/) 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 Test Query de busca expandida está desabilitado {: #netsuite-expanded-search-test-query}

-   **Sintoma:** Ao configurar uma pesquisa expandida na [atividade de Pesquisa do NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-search-activity/), 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 {: #netsuite-saved-search-fields-missing}

-   **Sintoma:** Uma [atividade de Pesquisa do NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-search-activity/) 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 do Test Query quando o filtro usa uma variável de projeto {: #netsuite-test-query-variable-date}

-   **Sintoma:** Quando um filtro de uma [atividade de Pesquisa do NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-search-activity/) usa uma [variável de projeto](/pt/integration-studio/design/variables/project/) 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 {: #netsuite-saved-search-result-fields-version}

-   **Sintoma:** Na [atividade de Pesquisa do NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-search-activity/), 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](/pt/management-console/agents/private/) 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` {: #netsuite-update-invalid-key-or-ref}

-   **Sintoma:** Uma atividade [Atualização](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-update-activity/) 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`](/pt/integration-studio/design/functions/xml-functions/#xmlfunctions-getxmlstring) para construir o payload de atualização a partir de uma resposta de pesquisa anterior.

    ```xml
    <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`](/pt/integration-studio/design/functions/string-functions/#stringfunctions-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 aos limites de registros da API {: #netsuite-record-limits}

-   **Sintoma:** Uma operação que usa o conector [NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/) 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](/pt/integration-studio/design/operations/settings/options/). 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](/pt/integration-studio/design/operations/settings/options/#enable-chunking).
    4.  Para referência mais detalhada, consulte [Informações detalhadas sobre chunking](/pt/integration-studio/design/operations/settings/options/#operationoptions-chunking).

### NetSuite: Limite de solicitações simultâneas excedido {: #netsuite-concurrency}

-   **Sintoma:** Operações de alto volume do [NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/) 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`](/pt/agent/jitterbit-conf/#operationengine) 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](/_download/attachments/70550228/NetSuiteReleaseNotes_2017.2.0.pdf) (páginas 71 e 72).

### NetSuite: Operações falham após atualizar a URL do WSDL {: #netsuite-wsdl-update}

-   **Sintoma:** Depois de atualizar a **URL de download do WSDL** em uma [conexão NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/netsuite-connection/) 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](/pt/integration-studio/design/connectors/netsuite/netsuite-how-tos/change-the-wsdl-version/). 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.

### Criar, atualizar ou fazer upsert no NetSuite falha com "is not a legal value for Country" {: #netsuite-country-enum-mismatch}

-   **Sintoma:** Uma atividade [NetSuite](/pt/integration-studio/design/connectors/netsuite/netsuite-connector-configuration/) **Criar**, **Atualizar** ou **Fazer upsert** falha quando o valor de origem de um campo de país não corresponde a um valor enum `Country` do NetSuite:

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

-   **Possível causa:** A API SuiteTalk do NetSuite exige que `Country` (e outros campos enumerados) seja um dos valores enum predefinidos do WSDL (por exemplo, `_unitedStates`). Um nome de país de exibição, um código de país ISO ou qualquer valor que não corresponda exatamente ao enum do WSDL é rejeitado.
-   **Resolução:**
    -   Na transformação que mapeia para o destino do NetSuite, traduza o valor de país de origem para o valor enum correspondente do NetSuite antes de escrever. Um dicionário de referência cruzada, uma instrução [`Case`](/pt/integration-studio/design/functions/logical-functions/#logicalfunctions-case) ou uma tabela de consulta funcionam para isso.
    -   Crie a referência cruzada a partir do enum `Country` definido no WSDL SuiteTalk do NetSuite que seu conector está usando. Os valores válidos mudam entre versões do WSDL, portanto, sempre verifique em relação à versão do WSDL configurada atualmente na conexão.
    -   Aplique a mesma abordagem a qualquer outro campo apoiado por um enum do NetSuite (por exemplo, `State`, `Currency`) onde os valores de origem ainda não correspondem ao enum do WSDL.

---

### Conjuntos de entidades OData v2 falham ao carregar com "Nenhum conjunto de entidades encontrado" {: #odata-v2-entity-sets}

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

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

-   **Possível causa:** O suporte para serviços OData V2 foi adicionado ao conector OData na versão do agente 11.59, através da configuração de conexão **Versão OData**. Em agentes anteriores à versão 11.59, o conector suporta apenas OData V4, portanto, uma conexão apontada para um serviço OData V2 não consegue preencher a lista de objetos. A mesma falha ocorre na versão 11.59 ou posterior se **Versão OData** for deixada em **V4** para um serviço OData V2.
-   **Resolução:**
    1.  Para agentes privados, atualize para a versão 11.59 ou posterior. Os agentes em nuvem recebem a atualização automaticamente.
    2.  Na [conexão OData](/pt/integration-studio/design/connectors/odata/connection/), defina **Versão OData** como **V2** (o padrão é **V4**). Salve e teste novamente a conexão.
    3.  Reabra a atividade **Consulta** OData. Os conjuntos de entidades devem ser carregados agora.

### OData: Microsoft Dynamics 365 retorna apenas os dados da empresa padrão {: #odata-dynamics-filter}

-   **Sintoma:** Uma conexão [OData](/pt/integration-studio/design/connectors/odata/) com um ponto de extremidade Microsoft Dynamics 365 Finance and Operations retorna dados apenas da empresa padrão do usuário, portanto, registros de outras empresas estão faltando nos resultados.
-   **Possível causa:** Por padrão, um ponto de extremidade OData do Dynamics 365 Finance and Operations retorna apenas os dados que pertencem à empresa padrão do usuário. Para dar à conexão um escopo entre empresas (expandido), uma cláusula de filtro entre empresas deve ser anexada à **URL de metadados OData** da conexão (a URL `$metadata`). Na URL de metadados, `?cross-company=true` por si só não aplica o escopo expandido.
-   **Resolução:** Na conexão OData, anexe uma cláusula de filtro `dataAreaId` à **URL de metadados OData**, substituindo `usrt` pelo seu identificador de área de dados e salve e teste novamente:

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

Para saber mais sobre como o Dynamics 365 delimita dados OData por empresa, consulte a documentação da Microsoft sobre [comportamento entre empresas](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/dev-itpro/data-entities/odata#cross-company-behavior).

### Oracle EBS: erro de conexão "arquivo JAR do provedor personalizado não está presente" {: #oracle-ebs-jdbc}

-   **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](/pt/integration-studio/design/connectors/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 {: #salesforce-record-limits}

-   **Sintoma:** Uma atividade padrão do [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/) (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 no máximo 200 registros por chamada. Quando mais registros são enviados em uma única chamada, o Salesforce rejeita o excesso. Isso pode acontecer quando o particionamento não está habilitado, ou quando está habilitado mas não é respeitado porque a origem é um conector baseado no Connector SDK, como o [HTTP v2](/pt/integration-studio/design/connectors/http-v2/). O particionamento não é suportado em origens baseadas em SDK, então todos os registros são enviados em uma única chamada, independentemente do tamanho de parte configurado (veja [Chunking não respeitado quando a fonte é um conector baseado em SDK](/pt/integration-studio/troubleshooting/operation/#chunking-sdk-source)).
-   **Resolução:**
    -   Habilite o [particionamento](/pt/integration-studio/design/operations/settings/options/) na operação e defina o tamanho da parte para 200 ou menos. Para instruções, consulte [Habilitar Chunking](/pt/integration-studio/design/operations/settings/options/#enable-chunking).
    -   Confirme se o tamanho da parte é 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 continuar sendo excedido mesmo com um tamanho de parte correto, contate o [suporte da Jitterbit](/pt/getting-started/support/).
    -   Para atividades em massa do Salesforce, aumente o tamanho padrão da parte de 200 para um valor maior, como 10.000, já que as atividades em massa são projetadas para lidar com grandes volumes de registros.

    O particionamento divide os dados durante a transformação, e não na recuperação. Quando a origem é uma atividade do Salesforce, cada parte é gravada em um arquivo temporário e os arquivos são combinados no destino final depois que todas as partes são processadas. Quando o destino é uma atividade do Salesforce, cada parte de origem produz uma parte de destino, com a transformação aplicada separadamente a cada uma, e as partes de destino resultantes são então combinadas. Para mais detalhes, consulte [Informações detalhadas sobre chunking](/pt/integration-studio/design/operations/settings/options/#operationoptions-chunking).

### Salesforce, Service Cloud e ServiceMax: autenticação multifator impede conexões com autenticação básica {: #salesforce-mfa}

-   **Sintoma:** Uma conexão que usa **Autenticação Básica** com o conector [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/), [Salesforce Service Cloud](/pt/integration-studio/design/connectors/salesforce-service-cloud/) ou [ServiceMax](/pt/integration-studio/design/connectors/servicemax/) falha no teste de conexão, ou conecta mas falha nas operações com um erro de autenticação.
-   **Causa:** Esses conectores compartilham a mesma base de código e autenticam em uma organização do Salesforce. A autenticação básica requer uma conta do Salesforce cujo conjunto de permissões atribuído não inclua 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á selecionada. Os tipos de login de integração do sistema estão isentos da exigência de MFA do Salesforce. Para detalhes, consulte a documentação do Salesforce [FAQ sobre Autenticação Multifator do Salesforce](https://help.salesforce.com/s/articleView?id=000388806&type=1).
    -   Se não for possível remover a MFA do usuário de integração, altere a conexão para usar autenticação OAuth 2.0 de 2 pernas.

!!! note
    O uso de OAuth 2.0 de 2 pernas requer a versão 11.59 ou posterior do agente. Em agentes 12.x, requer a versão 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 Nome Alternativo do Assunto (SAN) {: #salesforce-san}

-   **Sintoma:** Uma conexão do [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/) com um sandbox ou uma organização com Domínios Aprimorados habilitados falha com:

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

-   **Possíveis causas:**
    -   O certificado não inclui a URL do MyDomain ou do sandbox do Salesforce em seus Nomes Alternativos do Assunto.
    -   A caixa de seleção **Sandbox** nas configurações de conexão do Salesforce não está corretamente marcada.

-   **Resolução:**
    -   Inspecione as entradas SAN do certificado usando o OpenSSL: `openssl x509 -in cert.crt -text -noout`. Confirme se a seção Nome Alternativo do Assunto inclui a URL do seu MyDomain do Salesforce.
    -   Nas [configurações de conexão](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/salesforce-connection/) do Salesforce no Studio, verifique se a caixa de seleção **Sandbox** está definida corretamente para a sua organização de destino.
    -   Se a URL do Salesforce estiver ausente dos SANs, gere novamente o certificado para incluir o domínio específico.
    -   Se a mesma conexão for bem-sucedida em um grupo de agentes de nuvem, mas falhar em um agente privado, a causa pode ser, em vez disso, uma extensão SNI ausente no handshake TLS do agente. Consulte [A conexão com o sandbox do Salesforce falha devido a incompatibilidade de certificado](/pt/agent/troubleshooting/#salesforce-sandbox-sni).

### Conexão, configuração ou operação do Salesforce falha intermitentemente com `SERVER_UNAVAILABLE` {: #salesforce-server-unavailable}

-   **Sintoma:** Um teste de conexão do [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/), a configuração de uma atividade ou a execução de uma operação falha intermitentemente com:

    ```
    SERVER_UNAVAILABLE: server temporarily unavailable
    ```

    Por exemplo, isso pode ocorrer ao selecionar um objeto durante a configuração de uma atividade.

-   **Possível causa:** O Salesforce retorna esse código de falha quando o próprio servidor está temporariamente incapaz de processar a solicitação; o conector reporta isso com essa mensagem genérica em vez de repassar qualquer texto mais específico do Salesforce.
-   **Resolução:** Tente novamente o teste de conexão, a etapa de configuração ou a operação, aguardando mais tempo entre cada tentativa se a falha persistir. Se o erro persistir ou ocorrer com frequência, verifique o [Salesforce Trust](https://status.salesforce.com/) para um incidente relatado que afete sua instância, ou entre em contato com o Suporte da Salesforce. Um cenário relacionado é descrito no artigo da Salesforce [SERVER_UNAVAILABLE: Too Many Requests Waiting for Connections](https://help.salesforce.com/s/articleView?id=000387190&type=1).

### Salesforce: esquema de dados não inclui campos adicionados recentemente {: #salesforce-schema-refresh}

-   **Sintoma:** Um campo adicionado recentemente a um objeto do Salesforce não aparece no esquema de transformação ao configurar uma atividade do [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/).
-   **Causa:** O esquema de dados é armazenado em cache desde a última vez que a atividade foi configurada e não é atualizado automaticamente.
-   **Resolução:** Abra a configuração da 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 **Concluído** para salvar a configuração atualizada.

### Salesforce: mapeamento automático não mapeia campos quando uma atividade do Salesforce é o destino {: #salesforce-automap-extra-root-node}

-   **Sintoma:** Quando uma atividade do [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/) (como **Inserir** ou **Upsert**) é usada como o destino de uma transformação, usar o [Automap](/pt/integration-studio/design/transformations/map-identical-structures/) não mapeia nenhum campo.
-   **Causa:** O esquema da atividade do Salesforce inclui um nó raiz extra acima dos campos do objeto quando o esquema é espelhado. Esse nó raiz extra impede que o Automap corresponda os campos de origem aos campos de destino corretos.
-   **Resolução:**
    1.  No canvas de transformação, localize o nó do objeto de nível superior no lado de destino (por exemplo, **Account**).
    2.  Arraste o nó de origem correspondente para alinhá-lo manualmente com ele.
    3.  Com os nós alinhados, execute o **Automap** novamente. Os campos abaixo do nó serão mapeados automaticamente.

### Atividade de consulta do Salesforce: consulta pai-filho gera esquema hierárquico {: #salesforce-query-hierarchical-schema}

-   **Sintoma:** Uma [atividade de Consulta](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/salesforce-query-activity/) do Salesforce que usa uma declaração SOQL pai-filho gera um esquema de resposta hierárquico. Quando esse esquema é espelhado no lado de destino de uma transformação, a saída é um XML hierárquico em vez de uma estrutura plana.
-   **Causa:** O esquema hierárquico reflete o relacionamento pai-filho da consulta. Espelhar o esquema de origem no destino da transformação preserva essa hierarquia na saída.
-   **Resolução:**
    -   Para produzir uma saída plana, defina um esquema plano no lado de destino da transformação em vez de espelhar o esquema de origem.
    -   Se os resultados da consulta forem acessados em um script, os dados já estão disponíveis como uma estrutura plana, sem necessidade de configuração adicional.

### Salesforce: falha de upsert para alguns registros (ID externo duplicado) {: #salesforce-duplicate-external-id}

-   **Sintoma:** Uma operação **Upsert** ou **Bulk Upsert** do [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/) é concluída, mas relata falhas para alguns registros.
-   **Causa:** Vários registros de origem compartilham o mesmo valor de ID externo. Quando o ID externo não é exclusivo, o Salesforce retorna um erro e o upsert falha para esses registros.
-   **Resolução:**
    -   Verifique o arquivo de falha na página [Runtime](/pt/management-console/runtime/) do Management Console (aba **Registros de Atividade**) para identificar quais registros falharam.
    -   Garanta que o campo usado como ID externo tenha um valor exclusivo para cada registro. Consulte [Criar um ID externo do Salesforce para Jitterbit](/pt/integration-studio/design/connectors/salesforce/salesforce-how-tos/create-a-salesforce-external-id-for-jitterbit/).

### Atividade de inserção ou atualização do Salesforce: campo de ID de registro não pode ser mapeado {: #salesforce-record-id-mapping}

-   **Sintoma:** Uma transformação inclui um mapeamento para o campo de ID de registro do [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/) em uma atividade **Inserir** ou **Atualizar**, mas a operação não usa o valor mapeado.
-   **Causa:** O campo de ID de registro do Salesforce não pode conter um mapeamento nas atividades **Inserir** e **Atualizar**. O Salesforce atribui o ID do registro automaticamente na inserção; a atividade **Atualizar** identifica registros pelo seu ID existente do Salesforce, que não é um campo de destino mapeável.
-   **Resolução:** Remova o mapeamento para o campo de ID do registro na transformação. Se o objetivo for atualizar um registro específico pelo seu ID do Salesforce, verifique se os dados de origem fornecem esse ID e se a atividade **Atualizar** está configurada para corresponder registros a partir dele.

### Atividades de escrita em massa do Salesforce: primeiro registro de dados ignorado quando a origem não tem linha de cabeçalho {: #salesforce-bulk-activity-first-row}

-   **Sintoma:** Uma atividade de gravação em massa do [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/) (**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 gravação em massa do Salesforce sempre tratam a primeira linha dos dados de origem como a linha de cabeçalho das colunas. 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 o cabeçalho e não é gravado no Salesforce.
-   **Resolução:**
    -   Garanta que os dados de origem incluam uma linha de cabeçalho como a primeira linha. Os valores do cabeçalho devem corresponder aos nomes das colunas 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 de atividade em massa do Salesforce aparecem como "Incompleto" sem dados de entrada ou saída {: #salesforce-bulk-activity-incomplete-status}

-   **Sintoma:** Ao visualizar um log de operação que inclui uma atividade em massa do [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/) (**Bulk Insert**, **Bulk Upsert**, **Bulk Update**, **Bulk Delete** ou **Bulk Hard Delete**), a [entrada da etapa de operação](/pt/integration-studio/design/operations/logs/#component) da atividade em massa mostra um status **Incompleto** e não exibe dados de entrada ou saída, mesmo quando a operação é concluída com sucesso e os registros são processados.
-   **Causa:** As atividades em massa do Salesforce não geram dados de entrada e saída de componente no log da operação. O status **Incompleto** na etapa da atividade e a ausência de dados de entrada e saída são comportamentos esperados para todas as atividades em massa, independentemente do sucesso do processamento.
-   **Resolução:**
    -   Para determinar se os registros foram processados e se ocorreram erros, verifique as entradas de texto no log da operação para mensagens de erro ou confirmação de processamento bem-sucedido.
    -   Para agentes privados, você também pode baixar os resultados detalhados por registro: no Management Console, vá para a página [Runtime](/pt/management-console/runtime/), selecione a execução, abra a aba **Registros de Atividade** e baixe o arquivo de resultados.

### Atividades em massa do Salesforce falham quando acionadas por uma solicitação de API ou SOAP {: #salesforce-bulk-activity-api-soap}

-   **Sintoma:** Uma atividade em massa do [Salesforce](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/) (**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 de forma independente 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 suportam atividades em massa do Salesforce. Nesse contexto, o ID da organização não está disponível para o subsistema de carga 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 [Consulta](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/salesforce-query-activity/) padrão, ou uma **Bulk Update** por uma atividade [Atualizar](/pt/integration-studio/design/connectors/salesforce/salesforce-connector-configuration/salesforce-update-activity/) padrão. As atividades padrão funcionam corretamente nesse contexto.

### Eventos do Salesforce: eventos não podem ser habilitados após reinicialização do agente {: #salesforce-events-agent-restart}

-   **Sintoma:** Após um agente privado ser reiniciado ou reinstalado, os eventos do conector [Salesforce Events](/pt/integration-studio/design/connectors/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 {: #salesforce-events-limitations}

Os seguintes comportamentos das atividades de escuta do [Salesforce Events](/pt/integration-studio/design/connectors/salesforce-events/) ([Subscribe Event](/pt/integration-studio/design/connectors/salesforce-events/subscribe-event-activity/) e as atividades Subscribe [Insert](/pt/integration-studio/design/connectors/salesforce-events/subscribe-insert-cdc-event-activity/), [Update](/pt/integration-studio/design/connectors/salesforce-events/subscribe-update-cdc-event-activity/) e [Delete](/pt/integration-studio/design/connectors/salesforce-events/subscribe-delete-cdc-event-activity/) 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 {: #sap-multiple-activities}

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

### SAP RFC: "Nenhuma autorização RFC para o módulo de função BAPI_TRANSACTION_COMMIT" {: #sap-bapi-commit}

-   **Sintoma:** Uma atividade [RFC](/pt/integration-studio/design/connectors/sap/rfc-activity/) do SAP falha em tempo de execução com:

    ```
    JCoException occurred No RFC authorization for function module BAPI_TRANSACTION_COMMIT
    ```

-   **Possíveis causas:**
    -   A conta de usuário SAP na conexão não possui autorização S_RFC para `BAPI_TRANSACTION_COMMIT` ou seus grupos de função relacionados.
    -   O módulo de função `BAPI_TRANSACTION_COMMIT` não está configurado como habilitado para remoto no sistema SAP.
    -   A transformação de solicitação anterior à atividade não define o campo de controle de confirmação.

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

### Conexão SAP falha com "Chave de idioma inválida" {: #sap-invalid-language-key}

-   **Sintoma:** Uma conexão [SAP](/pt/integration-studio/design/connectors/sap/) falha durante a inicialização com um erro sobre a chave de idioma:

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

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

### ServiceNow: Execuções de operação inicial são lentas após reinicialização do agente ou em agentes em nuvem {: #servicenow-metadata-cache}

-   **Sintoma:** Operações que usam o conector [ServiceNow](/pt/integration-studio/design/connectors/servicenow/) executam lentamente em dois cenários:
    -   Em agentes privados, a primeira operação após a reinicialização do agente pode levar vários minutos; as execuções subsequentes são rápidas.
    -   Em agentes na nuvem, as execuções são intermitentemente lentas, levando minutos sempre que o cache de metadados do conector é atualizado.

    Isso pode causar timeouts de API a jusante.

-   **Possível causa:** O conector armazena em cache os metadados do ServiceNow de forma agressiva. Após uma reinicialização do agente em um agente privado (ou em cada execução para um agente na nuvem que não preservou o cache), a primeira operação deve reconstruir o cache, o que leva vários minutos.
-   **Resolução:**
    -   Em um agente privado, atenue a lentidão pós-reinicialização adicionando `getcolumnsmetadata=onUse` às **Opções Avançadas** do endpoint do ServiceNow. Esta configuração é eficaz apenas em agentes privados.
    -   Para desempenho consistente em agentes na nuvem, chame a API REST do ServiceNow através do conector [HTTP v2](/pt/integration-studio/design/connectors/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.

### Shopify: Seleções de objeto de atividade podem mudar após atualização de versão de API {: #shopify-api-version}

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

### Snowflake: Erro de espaço de heap Java ao consultar grandes conjuntos de dados {: #snowflake-query-heap}

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

    ```
    Error executing query activity. Exception is Java heap space
    ```

    O conector relata o erro desta forma porque envolve o erro Java subjacente, que aparece mais abaixo no rastreamento de pilha:

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

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

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

-   **Resolução:** Para grandes volumes de consultas, use o [conector Database](/pt/integration-studio/design/connectors/database/) com um driver JDBC do Snowflake em vez do conector Snowflake. O conector Database não armazena o conjunto de resultados completo na memória, portanto pode lidar com volumes de consultas muito maiores. [Instale o driver JDBC do Snowflake](/pt/agent/db-drivers/#install-a-jdbc-driver) no agente privado e configure uma conexão Database que o utilize. No agente 12.x e posterior, essa conexão Database também precisa de `enableArrowResultFormat=false&jdbc_query_result_format=json` em sua string de conexão; consulte [Snowflake: Operations fail on agent 12.x](#snowflake-jdbc-arrow-12x).

    Se precisar permanecer no conector Snowflake, qualquer um dos seguintes pode reduzir a pressão de memória, embora nenhum seja garantido como suficiente para conjuntos de dados na casa dos milhões de linhas:

    -   Divida a consulta em lotes usando as cláusulas SQL `LIMIT` e `OFFSET`, executando a operação repetidamente com offsets incrementais até que todas as linhas sejam processadas.
    -   Aumente o tamanho do heap JVM do Tomcat no agente privado (consulte [Tomcat heap memory](/pt/agent/java/#tomcat-heap-memory)).

### Snowflake: Operações falham no agente 12.x {: #snowflake-jdbc-arrow-12x}

-   **Sintoma:** Em um agente privado executando a versão 12.x, operações que consultam o Snowflake através de um driver JDBC do Snowflake (uma [conexão Database](/pt/integration-studio/design/connectors/database/) ou um script `DBExecute`) falham em tempo de execução, mesmo que o teste de conexão seja bem-sucedido. O erro faz referência à camada de memória Arrow do driver, por exemplo:

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

ou:

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

-   **Possível causa:** Por padrão, o driver JDBC do Snowflake retorna resultados de consultas no formato Apache Arrow, que não é compatível com a versão 12.x do agente e posteriores. Consulte o [artigo de solução de problemas do Snowflake sobre esse erro de módulo Java](https://docs.snowflake.com/en/developer-guide/snowpark/java/troubleshooting/#unnamed-module-error-on-java-17) para mais detalhes. O teste de conexão não retorna um conjunto de resultados, então ainda passa enquanto as consultas falham. Atualizar a versão do driver JDBC não resolve o problema.
-   **Resolução:** Defina `enableArrowResultFormat` como `false` e `jdbc_query_result_format` (ou `JDBC_QUERY_RESULT_FORMAT`) como `json` para que o driver retorne resultados em JSON em vez de Arrow:
    -   **[Conector de banco de dados](/pt/integration-studio/design/connectors/database/):** 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](/pt/integration-studio/design/connectors/snowflake/connection/#connection-custom-properties):** Em **Configurações opcionais > Propriedades personalizadas de conexão**, adicione `enableArrowResultFormat` com um valor de `false`. Uma linha `JDBC_QUERY_RESULT_FORMAT` com um valor de `JSON` já está presente lá por padrão.

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

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

    === "Linux"

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

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

        Em seguida, reinicie o agente.

    === "Windows"

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

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

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

    === "Docker"

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

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

            ```
            docker build -t my-agent .
            ```

        2.  Inclua no comando Docker `run`:

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

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

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

### Snowflake: Conexões baseadas em senha falhando após descontinuação de autenticação {: #snowflake-password-deprecated}

-   **Sintoma:** Operações que se conectam ao Snowflake usando o tipo de autenticação **Senha (Descontinuada)** começaram a falhar após funcionar anteriormente.
-   **Possível causa:** O Snowflake está descontinuando a autenticação de fator único (apenas senha). Conexões baseadas em senha falham a menos que a propriedade `TYPE` da conta de usuário do Snowflake esteja definida como `LEGACY_SERVICE`.
-   **Resolução:** Escolha uma das seguintes opções:
    -   **Solução temporária:** No Snowflake, defina a propriedade `TYPE` da conta de usuário como `LEGACY_SERVICE` para restaurar a conectividade baseada em senha:

        ```sql
        ALTER USER <username> SET TYPE = LEGACY_SERVICE;
        ```

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

    -   **Migração recomendada:** Atualize a conexão do conector [Snowflake](/pt/integration-studio/design/connectors/snowflake/) no Studio para usar autenticação **OAuth** ou **Chave-Par**, e configure a conta de usuário do Snowflake para corresponder.

### Snowflake: Instância de desenvolvedor está dormindo, tabelas de metadados não sendo preenchidas {: #snowflake-sleeping}

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

### Consulta do Snowflake: Incompatibilidade de caso do nó raiz do esquema plano causa erro `ProcessFlatStream` {: #snowflake-flatschema-case}

-   **Sintoma:** Uma atividade **Query** do [Snowflake](/pt/integration-studio/design/connectors/snowflake/) que usa um esquema simples falha em tempo de execução com:

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

    ProcessFlatStream error
    ```

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

-   **Possível causa:** O conector do Snowflake retorna o nome da tabela em minúsculas na resposta XML. Quando o Studio gera um esquema simples a partir da consulta, o nome do nó raiz é criado em maiúsculas. A incompatibilidade de maiúsculas e minúsculas entre o nó raiz do esquema (maiúsculas) e o nó raiz da resposta XML (minúsculas) causa falha no processamento do fluxo simples.
-   **Resolução:** Escolha uma das seguintes opções:
    -   No esquema simples, altere o nome do nó raiz para minúsculas para corresponder à saída do conector. Por exemplo, renomeie `SALES_ORDERS` para `sales_orders`.
    -   Use o esquema espelho com mapeamento padrão em vez de um esquema simples construído manualmente. O esquema espelho deriva sua estrutura diretamente da resposta do conector e não apresenta essa incompatibilidade de maiúsculas e minúsculas.

### Mesclagem do Snowflake: `stageName` e `fileContent` estão faltando no esquema de solicitação para estágios externos {: #snowflake-merge-external-stage}

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

### Inserção ou mesclagem do Snowflake: Erros de sintaxe SQL de caracteres especiais {: #snowflake-insert-special-chars}

-   **Sintoma:** Uma atividade **Insert** ou **Merge** do Snowflake falha com um erro de compilação SQL como:

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

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

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

-   **Resolução:**
    -   **Para valores contendo aspas simples:** Nas **Configurações opcionais** da [conexão](/pt/integration-studio/design/connectors/snowflake/connection/) do Snowflake, ative **Escape special characters**. Isso escapa automaticamente as aspas simples nos payloads das atividades **Insert** e **Invoke Stored Procedure**. Para atividades **Merge**, ou como alternativa para **Insert**, use [`SQLEscape`](/pt/integration-studio/design/functions/database-functions/#databasefunctions-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" {: #soap-no-wsdl-locator}

-   **Sintoma:** A implantação de um projeto que inclui uma conexão [SOAP](/pt/integration-studio/design/connectors/soap/), ou uma atividade [SOAP Request](/pt/integration-studio/design/connectors/api/soap-request-activity/) ou [SOAP Response](/pt/integration-studio/design/connectors/api/soap-response-activity/) da API falha com:

    ```
    Failed to deploy - Internal Error: No WSDL with locator
    ```

-   **Possíveis causas:**

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

-   O projeto foi implantado ou [transferido para outro ambiente](/pt/integration-studio/design/projects/migration/) antes do lançamento do Harmony 12.9, quando a implantação de um projeto podia deletar arquivos WSDL ainda em uso. O lançamento 12.9 previne a exclusão, mas um WSDL deletado antes disso ainda precisa ser re-enviado.

-   **Resolução:**

    1.  Re-envie o WSDL para o componente afetado:

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

    2.  Revise todas as transformações que herdam esquemas do WSDL re-enviado e [regenere-as](/pt/integration-studio/design/transformations/regeneration/#schemaregeneration-activity) 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](/pt/integration-studio/design/connectors/soap/soap-connection/#troubleshooting) para identificá-lo a partir de uma exportação JSON.

### WSDL SOAP: schemaLocation deve usar referências relativas {: #soap-schemalocation-relative}

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

### Conector SOAP reescreve prefixos e estrutura de namespace XML {: #soap-namespace-rewrite}

-   **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](/pt/integration-studio/design/connectors/http-v2/) apontando para a URL do serviço SOAP.
    2.  Em uma transformação, construa o envelope SOAP como uma string, concatenando literais de string e valores mapeados com o operador `+`. Alternativamente, leia um modelo de um arquivo e substitua valores dinâmicos com [`Replace`](/pt/integration-studio/design/functions/string-functions/#stringfunctions-replace).
    3.  Na atividade **POST** do HTTP v2, use o esquema de solicitação padrão (não envie um esquema de solicitação personalizado) e mapeie a string do envelope SOAP construída para o campo `body` desse esquema. O conector envia o valor `body` como está, preservando o XML literal.
    4.  Defina o cabeçalho **Content-Type** como `text/xml` ou `application/soap+xml` e defina o cabeçalho `SOAPAction` se o serviço exigir.
    5.  Leia a resposta do serviço no campo `responseContent` do esquema de resposta padrão da atividade.

### SOAP: Mensagens MTOM/XOP não são suportadas {: #soap-mtom}

-   **Sintoma:** O [conector SOAP](/pt/integration-studio/design/connectors/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](/pt/integration-studio/how-to/support-soap-mtom-xop/), 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" {: #vtex-test-permissions}

-   **Sintoma:** Um teste de conexão do [VTEX](/pt/integration-studio/design/connectors/vtex/) falha com um erro de permissão no Studio, mesmo que as mesmas credenciais funcionem em ferramentas externas como Postman.

    ```
    You don't have permission to access this resource
    ```

-   **Possível causa:** O usuário VTEX ou a chave de aplicação associada à conexão não possui uma ou mais permissões que o conector usa para validar a conexão. Essas permissões são mais rigorosas do que as necessárias para acesso básico aos dados.
-   **Resolução:**
    1.  No portal administrativo do VTEX, abra o perfil de acesso atribuído ao usuário ou à chave de aplicação que o Jitterbit está usando.
    2.  Confirme que o perfil de acesso inclui o recurso **License Manager** com acesso ao recurso **Get account by identifier**.
    3.  Salve o perfil e teste novamente a conexão VTEX no Studio.

### Workday: WSDL v42.0 e v42.1 retornam erros para serviços específicos {: #workday-wsdl-v42}

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

### Workday: Teste de conexão falha com "A tarefa enviada não está autorizada" {: #workday-not-authorized}

-   **Sintoma:** Um teste de conexão do [Workday](/pt/integration-studio/design/connectors/workday/) falha com:

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

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

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

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

### Chunking não é respeitado quando a origem é um conector baseado em SDK {: #chunking-sdk-source}

-   **Sintoma:** Uma operação com [divisão em lotes](/pt/integration-studio/design/operations/settings/options/#enable-chunking) ativada envia todos os registros para o destino em um único lote em vez de respeitar o tamanho de lote configurado. Erros do destino indicam que o limite de lote foi excedido (por exemplo, o Salesforce retorna `EXCEEDED_ID_LIMIT: record limit reached. cannot submit more than 200 records into this call`).
-   **Possível causa:** A divisão em lotes não é suportada quando a origem é um conector baseado em Connector SDK (conforme listado na coluna **Connector type** da [lista de conectores](/pt/integration-studio/design/connectors/#types)). Operações que usam origens não-SDK, como [HTTP](/pt/integration-studio/design/connectors/http/), [Database](/pt/integration-studio/design/connectors/database/), [Variable](/pt/integration-studio/design/connectors/variable/) e [Local Storage](/pt/integration-studio/design/connectors/local-storage/), respeitam a divisão em lotes normalmente.
-   **Resolução:**
    -   Se a divisão em lotes não for necessária, desative-a nas [opções de operação](/pt/integration-studio/design/operations/settings/options/#enable-chunking).
    -   Se a divisão em lotes for necessária, divida a operação em duas:
        -   Na primeira operação, leia da origem baseada em SDK e escreva em uma atividade Variable [Write](/pt/integration-studio/design/connectors/variable/variable-write-activity/).
        -   Na segunda operação, leia de uma atividade Variable [Read](/pt/integration-studio/design/connectors/variable/variable-read-activity/) e escreva no destino original com a divisão em lotes ativada. Como o conector Variable não é baseado em SDK, a divisão em lotes funciona corretamente nesta operação. Para as etapas de configuração de divisão em lotes, consulte [Configurar divisão em lotes de operação](/pt/integration-studio/how-to/configure-operation-chunking/).

### Agente offline ou inacessível {: #agent-offline}

-   **Sintoma:** A aba [Privada](/pt/management-console/agents/private/) da página **Agentes** do Console de Gerenciamento mostra o agente como **Desconhecido** ou **Parado**, ou o Studio exibe um erro `Agente Não Está Executando ou Inacessível`.
-   **Causas possíveis:**
    -   Os serviços da Jitterbit não estão em execução.
    -   Os serviços estão em execução, mas o host do agente não consegue acessar a nuvem Harmony.
    -   Um proxy corporativo está impedindo a conexão do agente.

-   **Resolução:**
    -   Se os serviços do Jitterbit não estiverem em execução, inicie-os:

        -   **Windows:** Veja [Iniciar um agente do Windows](/pt/agent/windows/#start).
        -   **Linux:** Veja [Iniciar um agente do Linux](/pt/agent/linux/#start).

        Se o serviço falhar ao iniciar, verifique o seguinte em busca de mensagens de erro:

        -   **Windows:** `C:\Program Files (x86)\Jitterbit Agent\log` e o log de **Aplicativos do Visualizador de Eventos** do Windows.
        -   **Linux:** `/opt/jitterbit/log`.

        A conta que executa os serviços do Jitterbit requer direitos de administrador local no Windows e acesso total ao diretório de instalação do Jitterbit.

    -   Se os serviços estiverem em execução, mas não conseguirem acessar 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 pode acessar o [portal Harmony](/pt/getting-started/harmony-portal/) na porta 443.

    -   Se o agente se conectar através de um proxy corporativo, verifique se o proxy está configurado corretamente para o agente, incluindo o domínio NTLM se o proxy usar autenticação NTLM. Veja [Servidor proxy para agentes privados do Jitterbit](/pt/agent/proxy/). O log de negação do servidor proxy é útil para diagnosticar o que o proxy está bloqueando.

    -   Se os serviços do agente estiverem saudáveis no host (`jitterbit status` mostra todos os serviços em execução), mas o agente alternar repetidamente para **Desconhecido**, ou ciclar entre **Executando**, **Desconhecido** e **Parado**, a conexão ou o processo do agente provavelmente está sendo interrompido entre os batimentos cardíacos. Verifique as seguintes causas possíveis:

        -   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 os batimentos cardíacos. Tente reduzir o intervalo de batimento cardíaco do agente (`agent.heart.beat.interval`). Para agentes hospedados na nuvem, veja [Azure VM: Conexões perdidas e erros de WebSocket/I/O](#azure), que também se aplica a outras redes restritas, como AWS.
        -   O agente pode ter travado sob pressão de memória. Verifique se há arquivos de despejo de falha `OutOfMemoryError` ou `hs_err_pid`. Veja [Espaço de heap do Java: `OutOfMemoryError`](#oom).
        -   Se os agentes foram recentemente migrados para um novo sistema operacional enquanto reutilizavam um grupo de agentes que anteriormente hospedava agentes no antigo SO, o grupo reutilizado pode ser a causa. Veja [Agente mostra Desconhecido ou Parado após reutilizar um grupo de agentes entre sistemas operacionais](#migrated-group-os).

### Agente mostrando versões ou endereços IP diferentes {: #agent-cloned}

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

### Falha de sincronização do agente: Alterações de projeto não sendo aplicadas {: #sync-failure}

-   **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.
-   **Causas possíveis:**
    -   A implantação utilizou [Implantação Configurável](/pt/integration-studio/design/projects/deployment/#configurable-deploy), que implanta apenas os fluxos de trabalho e operações selecionados. Qualquer parte do projeto fora dessa seleção permanece na versão previamente implantada no agente.
    -   O componente não é utilizado no fluxo lógico de um fluxo de trabalho 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.
    -   Um tempo limite de rede ou erro de autorização ocorreu durante a sincronização.
    -   O espaço em disco baixo no host do agente impediu que os arquivos do projeto sincronizado fossem gravados.

-   **Resolução:**
    -   Reimplantar o projeto completo: no Studio, use [Implantar](/pt/integration-studio/design/projects/deployment/#deploy), que implanta todas as operações do projeto, em vez de uma [Implantação Configurável](/pt/integration-studio/design/projects/deployment/#configurable-deploy) de apenas fluxos de trabalho ou operações selecionados.
    -   Reinicie os serviços do agente para forçar uma nova sincronização de todos os projetos implantados.
    -   Revise os [logs do agente](/pt/agent/log/) em busca de tempos limite de rede ou erros de autorização relacionados à sincronizaçã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. Veja [Espaço em disco e acúmulo de logs](#disk-space).

### Erro 1722 na instalação do Windows {: #win-error-1722}

-   **Sintoma:** A instalação do agente privado do Windows falha durante o processo, com um desses erros do Instalador do Windows:

    ```
    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 no 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 incluído no 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 incluído e o serviço do Windows `jitterbitpostgres` podem não ser totalmente criados. A mensagem pode, em vez disso, nomear uma ação diferente, como `InstallVerboseLogShipper`.

-   **Causas possíveis:**
    -   Um Microsoft Visual C++ Redistributable ausente ou em conflito (o PostgreSQL incluído requer isso).
    -   Caracteres proibidos na senha do PostgreSQL.
    -   Em uma reinstalação, componentes remanescentes do PostgreSQL de um agente anterior. O desinstalador do agente não remove o PostgreSQL, o usuário do Windows `jitterbitpostgres` ou suas entradas de registro por design, e esses remanescentes 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 remanescentes do serviço de envio de logs detalhados de um agente anterior. Assim como com o PostgreSQL, uma desinstalação padrão não remove o serviço de envio de logs detalhados ou seus arquivos, e esses remanescentes podem causar a falha da ação `InstallVerboseLogShipper` do instalador.

-   **Solução:**
    -   Instale o Microsoft Visual C++ Redistributable de 64 bits para Visual Studio usando `vc_redist.x64.exe` (cobre o 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, mude a [senha para uma válida](/pt/agent/postgresql/#password-character-restrictions) antes de tentar a instalação novamente.

        !!! note "Nota"
            Nos 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](/pt/agent/postgresql/#password-character-restrictions) no momento da entrada e solicita que você a corrija antes que o PostgreSQL seja instalado.

    -   Se você estiver reinstalando após um agente anterior, remova completamente o PostgreSQL restante primeiro: siga [Desinstalar um agente privado do Windows](/pt/agent/windows/#uninstall), depois confirme que o usuário do Windows `jitterbitpostgres`, os diretórios do programa e dos dados do PostgreSQL e as chaves de registro do PostgreSQL foram removidos.
    -   Se a mensagem de erro 1722 mencionar 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 ainda falhar após uma limpeza completa, entre em contato com o [suporte da Jitterbit](/pt/getting-started/support/).

### Serviço PostgreSQL removido após falha de atualização no Windows {: #postgres-service-removed}

-   **Sintoma:** Após uma falha na atualização do 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 agentes privados anteriores a 11.59 / 12.3 quando uma senha incorreta é inserida durante a atualização e o instalador falha ao reverter corretamente. Este problema é resolvido nos agentes privados 11.59 / 12.3 e posteriores, onde uma senha incorreta bloqueia a atualização na mesma caixa de diálogo e permite a reentrada ou cancelamento sem afetar a instalação existente.

-   **Resolução:**
    1.  Abra um prompt de comando como administrador.
    2.  Re-registre o serviço PostgreSQL:

        ```bat
        "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 versão do PostgreSQL. Para encontrá-lo, consulte [versão do PostgreSQL incluída com o agente privado](/pt/agent/postgresql/#same-version-as-bundled).

    3.  Inicie os serviços do PostgreSQL e PgBouncer:

        ```bat
        net start postgresql-x64-<VERSION>
        net start JitterbitPgbouncer
        ```

    4.  Inicie todos os serviços do agente Jitterbit:

        ```bat
        "C:\Program Files\Jitterbit Agent\StartServices.bat"
        ```

    5.  Uma vez que o agente esteja em execução, [reinicie as senhas do administrador do PostgreSQL e da conta de serviço](/pt/agent/how-to/reset-the-postgresql-admin-password/) antes de tentar a atualização novamente.

### Os serviços do Agent falham ao iniciar após reiniciar o Windows após uma atualização {: #postgres-old-service-blocks-restart}

-   **Sintoma:** Uma atualização de agente privado do Windows de um agente 11.x para um agente 12.x anterior à versão 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 do Windows anterior (`postgresql-x64-<VERSION>`, em que `<VERSION>` é a versão instalada pelo agente anterior) com seu tipo de inicialização ainda definido como **Automático**. Ao reiniciar, 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, seja iniciado.

-   **Resolução:**
    -   Atualize para a versão 12.10 ou posterior do agente, que remove o serviço PostgreSQL anterior durante a atualização.
    -   Em uma versão anterior do agente, após a atualização, abra os Serviços do Windows, identifique o serviço `postgresql-x64-<VERSION>` mais antigo (o que antecede a atualização) e defina seu tipo de inicialização como **Manual** ou **Desativado**, ou desinstale-o, antes de reiniciar o sistema host. Para verificar qual versão está atualmente empacotada com o agente, execute o comando em [Mesma versão que a incluída](/pt/agent/postgresql/#same-version-as-bundled).

### A autenticação de dois fatores impede a instalação do agent Windows de 64 bits {: #tfa-install}

-   **Sintoma:** A instalação de um agente privado Windows de 64 bits falha quando a autenticação de dois fatores (TFA) está ativada na organização.
-   **Resolução:** Desative temporariamente a TFA, instale o agente e, em seguida, reative 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 a partir da página [Organizações](/pt/management-console/organizations/#edit-organization-policies) do Console de Gerenciamento.

### A instalação do Linux sem privilégios de root falha {: #linux-nonroot}

-   **Sintoma:** O instalador **Linux Redhat Non-Root (x64)** falha.
-   **Resolução:** Verifique o seguinte:
    -   O usuário não-root tem privilégios `sudo`. Um administrador do sistema deve adicionar o usuário ao grupo `wheel`. Para verificar a associação atual ao grupo, execute `groups`.
    -   Ao fazer login como usuário `jitterbit`, a variável de ambiente `JITTERBIT_HOME` está definida para o local de instalação:

```sh
echo $JITTERBIT_HOME

O resultado deve ser /opt/jitterbit. Isso é configurado por $HOME/.bashrc.d/jitterbit quando as instruções de instalação são seguidas. Para configurá-lo manualmente, execute:

. /opt/jitterbit/scripts/set.env

Se o instalador falhar com um erro OPENSSL_3.4.0, este é um problema conhecido no RHEL 9.7 e versões posteriores. Veja A instalação de agente privado não-root no RHEL 9.7 e versões posteriores apresenta um erro OpenSSL nas questões conhecidas do agente privado para uma solução alternativa.

Driver JDBC: "Nenhum driver adequado encontrado"

Sintoma: Uma conexão com o banco de dados falha porque o driver JDBC necessário não está instalado no agente, com um erro como Nenhum driver adequado encontrado para 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 driver .jar para JITTERBIT_HOME/tomcat/drivers/lib/, em seguida, reinicie o agente. Para os passos completos, veja 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 do heap Java do agente privado (-Xmx) é muito pequeno para a carga de trabalho (arquivos grandes ou alta concorrência de jobs).
Resolução:
1. Aumente o tamanho máximo do heap Java do agente privado. Veja Memória heap do Tomcat para saber como alterar o valor de -Xmx (por exemplo, de -Xmx1024m para -Xmx4096m).
2. Reinicie os serviços do agente após fazer a alteração.
3. Para operações que processam arquivos grandes, configure divisão para reduzir o uso de memória por job. O Studio aplica transformações de streaming automaticamente onde elas se qualificam.
4. Se a observabilidade nativa estiver habilitada, use o gráfico Capacidade de Recursos do Sistema 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 corretamente 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 causar a parada do PostgreSQL ou falhas nas operações com erros de permissão. Arquivos de log e temporários se acumulam nos diretórios do agente, especialmente em agentes que processam altos volumes.
Resolução:
- Verifique o espaço em disco disponível no host do agente.
- Identifique 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. Veja 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 falhada se repetindo em ProcessEngine.log). Limpe arquivos excessivamente grandes se o espaço estiver criticamente baixo; limpar o arquivo e reiniciar o agente também pode parar o erro subjacente.
- Confirme se o serviço de limpeza está em execução e se sua retenção está sendo respeitada. Na seção [FileCleanup] do jitterbit.conf, verifique se AutoStart está como true e revise FrequencyInHours. A retenção por diretório é definida em CleanupRules.xml usando NumDays ou NumOfHours.
- Se o serviço de limpeza não puder excluir arquivos de log ativos (o Tomcat mantém seus logs stdout e stderr abertos no Windows), aumente o FileAge para aquele diretório em CleanupRules.xml para pelo menos um dia, para que a limpeza não tenha como alvo arquivos que ainda estão sendo gravados.
- Se grandes arquivos de despejo de falhas .dmp estiverem consumindo o disco, veja Arquivos de mini-despejo do JVM preenchem o disco do agente.

Falhas de conexão com `TranDb`

Sintoma: As operações falham com erros que fazem referência ao banco de dados PostgreSQL interno do agente privado, ou os serviços internos do agente falham ao iniciar porque o limite de conexões foi atingido. Falhas repetidas também podem inundar ProcessEngine.log, fazendo com que cresça 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
```
Causas possíveis:
- O limite max_connections do PostgreSQL interno, ou o limite max_db_connections do PgBouncer, é muito baixo para a carga de trabalho do agente.
- As operações estão se acumulando sob carga pesada ou uma desaceleração de rede ou de endpoint, mantendo conexões de banco de dados até que o pool do PgBouncer esteja esgotado (query_wait_timeout).
- Em um agente Windows, o IP Helper está interferindo nas conexões locais do banco de dados do agente.
Resolução:
- Versões recentes do agente vêm com limites de conexão do PostgreSQL e PgBouncer mais altos por padrão, então primeiro confirme se o agente está em uma versão atual. Se um agente atual ainda esgotar seu limite de conexão, entre em contato com o suporte da Jitterbit para aumentá-lo sob orientação de suporte. As instâncias do PostgreSQL e PgBouncer incluídas 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 agente e qualquer lentidão de rede ou de endpoint que esteja acumulando operações.
- Em um agente Windows, desative o IP Helper. Veja problema de IPv6 no Windows.

PostgreSQL: Encerramento rápido administrativo

Sintoma: Todas as operações falham porque o banco de dados do agente está indisponível (as operações podem ficar em status Pendente), e o log do PostgreSQL registra um desligamento 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 uma tarefa agendada, ou uma ferramenta de monitoramento ou backup que reinicia serviços.
- O host do agente ficou sem CPU ou memória, fazendo com que o Tomcat falhasse e levando o PostgreSQL junto.
Resolução:
- Reinicie os serviços do PostgreSQL e do agente Jitterbit (ou reinicie o host do agente) para recuperar. Se as operações permanecerem travadas em um estado Pendente ou Executando após o PostgreSQL voltar, entre em contato com o suporte Jitterbit, pois o pool de conexões do banco de dados do agente pode não ter se recuperado.
- Identifique o que parou o PostgreSQL: verifique o log de eventos do SO (no Windows, Visualizador de Eventos) em torno do momento da falha para reinicializações, atualizações, tarefas agendadas, falhas de serviços ou ferramentas de backup e monitoramento que reiniciam serviços. Previna ou reprograma o que estiver parando, e configure o serviço PostgreSQL para reiniciar automaticamente em caso de falha.
- Verifique a CPU e a memória do host do agente. Se os serviços Jitterbit estiverem falhando sob carga, consulte Loop de reinicialização do serviço do agente e Espaço de heap Java: OutOfMemoryError.

Falha no handshake de certificado (TLS)

Sintoma: As operações conectando-se a pontos finais seguros falham durante a negociação 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 ponto final usa renegociação TLS legada, que o agente bloqueia por padrão.
- O agente e o ponto final não conseguem negociar uma versão ou cifra TLS comum. Agentes das versões 11.x e 12.x possuem bibliotecas de segurança diferentes, portanto, um ponto final que falha ao conectar em um agente 11.x pode ter sucesso em um agente 12.x.
- O certificado do ponto final (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: A partir do host do agente, execute o seguinte para confirmar qual versão do TLS o endpoint negocia e se o handshake é bem-sucedido no nível da 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] do jitterbit.conf e reinicie o agente. Essa configuração requer a versão 11.39 ou posterior do agente.
- 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), em seguida, 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. Veja SQL Server: A conexão falha com um erro de caminho de certificado PKIX.
- Se uma falha de negociação ou handshake do TLS 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 certificados atualizado.

FTP: Tempo limite da conexão de dados excedido

Sintoma: O login FTP é bem-sucedido, mas a listagem de arquivos ou a transferência de arquivos trava e expira.
Possíveis causas:
- O modo de conexão FTP (ativo vs. passivo) é incompatível com a configuração da rede ou do firewall.
- O intervalo de portas passivas definido no servidor FTP não está aberto no firewall corporativo.
Solução:
- Nas configurações de conexão FTP, altere 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 de nível de conexão, ative o registro de depuração do curl definindo CurlDebugDir na seção [Settings] de jitterbit.conf. Veja os logs do Curl.

Problema de IPv6 no Windows

Sintoma: Alguns agentes enfrentam problemas de conectividade quando o IPv6 está habilitado no host Windows. Isso pode se manifestar, por exemplo, como operações travadas em um estado Pendente com um ProcessEngine.log crescendo rapidamente, quando o serviço IP Helper falha e o agente perde a conexão com o banco de dados interno.
Solução: Desative tanto o IPv6 quanto o 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 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, depois defina o Tipo de inicialização como Desativado:

VM do Azure: Conexões perdidas 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: Conexões perdidas e erros de WebSocket/I/O no guia de solução de problemas do agent para obter as etapas completas.

Apache: Nenhum `ConfigArgs` 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 que o deadlock recorre sob carga.
Possíveis causas:
- O pool de conexões do banco de dados do agente entra em 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 os timeouts padrão.
- Processos obsoletos do Jitterbit estão segurando 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 parados sem que todos os processos do Jitterbit terminem corretamente.
- O host do agente está sobrecarregado por atividade de pico, ou sua CPU está sendo estrangulada. Por exemplo, uma instância de nuvem com capacidade de explosão (como um tipo t3 da AWS) estrangula sua CPU uma vez que seus créditos de explosão são esgotados, o que pode privar o PostgreSQL interno sob carga.
Resolução:
- Pare todos os serviços do Jitterbit, finalize qualquer processo do Jitterbit que ainda esteja em execução e, em seguida, reinicie os serviços para eliminar o deadlock.
- Se o deadlock estiver no pool de conexões Java (c3p0) e o PostgreSQL estiver saudável, mude o agente para seu pool de conexões interno em C++ definindo UseInternalPooling=true na seção [DbInfo] de jitterbit.conf, e então 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 em nuvem, use um tipo de instância com desempenho de CPU sustentado (não explosivo).
- Antes de atualizar um agente, drain stop ele e deixe as operações em execução terminarem, para que nenhum processo fique segurando conexões de banco de dados durante a atualização. Em ambientes movimentados, permita tempo extra para a conclusão do drain stop.

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

Sintoma: Os 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.

Causas possíveis:
- Um processo do agente está mantendo o arquivo aberto. No Windows, o serviço de limpeza não pode remover um arquivo que está 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 em arquivos no 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 assim que não estiverem mais em uso. Reinicie o agente após editar o arquivo.
- Exclua os logs stdout e stderr do Tomcat, que são 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.

O 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 parado. Isso se aplica a agentes Docker que usam um volume persistente para /opt/jitterbit/Resources, e a agentes Linux não conteinerizados.
Causa: Quando o agente para com deregisterAgentOnDrainstop=true, ele se desregistra do 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á habilitado desregistra automaticamente o agente existente e registra um novo. Os passos abaixo se aplicam a agentes Docker em versões anteriores e a agentes Linux em qualquer versão.
Solução: Remova o arquivo credentials.txt obsoleto e, em seguida, reinicie o agente para acionar um novo registro.

Em um agente Linux não conteinerizado, 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.

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

Sintoma: Após ativar ou desativar o Log em nuvem 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 Log em nuvem na página Agents, reinicie todos os agents privados do grupo para que a alteração tenha efeito.

Não é permitido adicionar um segundo agent a um grupo de agents Standard

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 Alta Disponibilidade, que requer uma licença de Agent grouping for HA.
Resolução:
- Na página Agents, edite o grupo de agents e altere a Classe do grupo de agents para Alta Disponibilidade.
- 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.

A adição de um agent privado falha com um erro de limite máximo de agents

Sintoma: Na gaveta Detalhes do grupo de agents de um grupo de agents, o ícone Criar está disponível, mas salvar o novo agent privado falha com um erro de máximo de agents. 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.
```
  Este limite se aplica a grupos com a classe de grupo de agentes High Availability. Um grupo Standard permite apenas um agente, conforme descrito em Adicionar um segundo agente a um grupo de agentes Standard 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.
```
  Este 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 Dashboard 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 Customer Success Manager.

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 Starting, Stopped, Unregistered ou Unknown. Agentes nos estados Running ou Stopping 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 ignorada 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 Test 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:
- Action > Update connectors é selecionado para o grupo de agentes na página Agentes do Console de Gerenciamento. Esta 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, então 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 conectores serão atualizados. Veja 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 previne 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, de Windows para Linux) enquanto reutiliza o mesmo grupo de agentes, os agentes migrados intermitentemente aparecem como Desconhecido ou Parado na aba Privada da página Agentes do Console de Gerenciamento, mesmo que jitterbit status mostre os serviços em execução e as operações ocorram normalmente.
Possível causa: Reutilizar um grupo de agentes do sistema operacional anterior pode deixar para trás metadados que interferem na comunicação de status para os novos agentes. O efeito é tipicamente cosmético: os serviços e operações continuam a funcionar 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, em seguida, registre os agentes lá.

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

Sintoma: Após implantar um projeto no Studio, operações acionadas não começam imediatamente, ou um breve acúmulo de operações enfileiradas aparece.
Causa: O ambiente está 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 estão durando, escaneie jitterbit-agent.log em busca de environment-deploy. 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, veja 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 da Jitterbit.

Agent mostrando como incapaz

Sintoma: Operações enviadas ao grupo de agentes estão sendo reprocessadas 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:
- Cada thread de trabalho no mecanismo de processo do agente já está em uso, portanto, o agente não pode aceitar outra operação até que uma thread seja liberada. O tamanho do pool é definido por MaxNumberOfWorkerThreads na seção [ProcessEngine] do jitterbit.conf.
- Uma métrica de capacidade opcional está habilitada 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] do 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 habilitadas. O Apache atende apenas a solicitações de API, portanto, o uso de threads do Apache é relevante apenas em um agente que lida com 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 em busca de longas sequências de alterações no status de capacidade para confirmar que o agente está alternando entre estados incapazes, e então investigue o seguinte:
- Se muitas operações estão sendo executadas simultaneamente, revise MaxNumberOfWorkerThreads na seção [ProcessEngine] do 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 habilitadas na seção [AgentCapability]. Se nenhuma estiver habilitada, 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 habilitado, verifique-o antes das métricas de thread: qualquer um que ultrapasse 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 habilitada, revise os gráficos de Capacidade de Recursos do Sistema, Threads do Apache e Threads do Tomcat na aba Métricas da página Agentes do Console de Gerenciamento. Ao revisar gráficos para um grupo de múltiplos agentes, use valores de pico ou máximos em vez de médias, pois as médias podem mascarar um único agente sobrecarregado enquanto o restante do grupo parece saudável.
- Se o grupo de agentes contiver 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 falhou. Se apenas um agente estava incapaz, a operação deveria ter sido direcionada a um agente capaz. Verifique se o balanceamento de carga está configurado corretamente para o grupo.
- Se os limites de recursos estão sendo constantemente atingidos, adicione agentes ao grupo para distribuir a carga.
- Se a pressão de memória for o gatilho, veja 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 local de arquivos 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]

Causa possível: Os metadados de implantação de um arquivo não foram totalmente sincronizados do cloud Harmony para o agente, então o agente não consegue localizar o arquivo em tempo de execução. Isso geralmente é transitório (por exemplo, uma breve interrupção de sincronização), mas também pode ocorrer após a exportação e reimportação de um projeto entre ambientes.
Resolução:
1. Execute novamente a operação. Na versão do agente 11.38 e posteriores, o agente se autocorrige nessa 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 do ambiente (na próxima execução da 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 haja um problema mais profundo, como um ambiente que atingiu seu limite de registros de implantação ou uma regressão específica de versão. Entre em contato com o suporte Jitterbit com o nome da operação que falhou e os 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, em seguida, reinstale o software do agente.

Conector não baixado para o agent

Sintoma: As operações falham com erros indicando que um conector está indisponível ou não encontrado no agente, tipicamente após uma nova versão do conector ser lançada ou após implantar um projeto que usa um conector baseado no SDK do Conector:
```
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 necessária pelo projeto ainda não foi baixada da nuvem para o agente. Isso é frequentemente transitório e se resolve dentro de alguns minutos.
- Para agentes privados: o agente não consegue acessar a nuvem Harmony para baixar o conector.
Resolução:
- No Studio, abra a conexão afetada e clique em Testar. Isso faz com que o agente baixe a versão mais recente do conector da nuvem.
- Se o conector ainda não for baixado, verifique se a política organizacional Desativar Atualização Automática de Conectores está habilitada. Quando está habilitada, o botão Testar não baixa versões de conectores. Veja Gerenciamento de Agentes.
- Para baixar o conector sem alterar a política, vá para a página Agentes do Console de Gerenciamento, selecione o grupo de agentes e escolha Ação > Atualizar conectores. Isso força uma atualização de conector em todo o grupo e não é afetado pela política Desativar Atualização Automática de Conectores.
- Para agentes privados, verifique se o host do agente consegue acessar a nuvem Harmony. Veja Agente offline ou inacessível.

Nota

Os conectores Microsoft Excel e Excel v2 falham ao carregar com este erro especificamente na versão 12.x do agente privado. Este é um problema conhecido com uma solução alternativa separada. Veja Conectores Excel e Excel v2 falham ao carregar nas questões conhecidas do agente privado.

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

Sintoma: A instalação de um agente privado em um host atrás de um proxy corporativo falha durante a etapa de registro inicial, e o instalador informa que não conseguiu acessar a nuvem Harmony:
```
Could not connect to Jitterbit Harmony cloud
```
Causas possíveis:
- O proxy está bloqueando a conexão do agente com a nuvem Harmony durante o registro.
- O proxy requer autenticação que a configuração de proxy do agente não fornece. Agentes privados suportam autenticação de proxy, incluindo um domínio NTLM. Veja Servidor proxy para agentes privados Jitterbit.
Resolução:
1. Configure o proxy durante a configuração do agente para que o instalador possa acessar a nuvem Harmony através dele, fornecendo as credenciais do proxy (e o domínio NTLM, se o proxy exigir). Veja Configurar um proxy durante a configuração do agente.
2. Se o registro ainda falhar através do proxy, peça à sua equipe de rede para permitir os domínios e endereços IP do Jitterbit através do proxy, ou contornar o proxy para eles. As URLs específicas da região do Harmony estão documentadas em Informações da lista de permissão.
3. Execute o instalador novamente assim que o proxy estiver configurado ou o host puder acessar 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 as operações falham com erros como O serviço Tomcat não está em execução. Se jitterbit status mostrar todos os serviços saudáveis no host, mas o status exibido apenas oscila entre Executando, Desconhecido e Parado, isso é um problema de conectividade em vez de um loop de falhas. Veja Agente offline ou inacessível.
Causas possíveis:
- Um processo Jitterbit órfão de uma execução anterior (um processo Tomcat, Process Engine ou scheduler) ainda está ocupando a porta do serviço, então cada reinicialização falha com java.net.BindException: Endereço já em uso e o agente entra em ciclo.
- O host fica sem memória e o sistema operacional termina o processo. Isso pode acontecer quando o host tem memória insuficiente para a carga de trabalho ou quando o limite de memória de um contêiner está definido muito baixo.
- O host do agente está com pouco espaço em disco, ou o banco de dados interno do PostgreSQL cresceu o suficiente para falhar na inicialização.
- O Process Engine está falhando repetidamente sob carga sustentada.
Resolução:
- Confirme se este é um verdadeiro loop de falhas. Verifique os logs do Tomcat em JITTERBIT_HOME/tomcat/logs/ e ProcessEngine.log para a exceção registrada em cada reinício. Um java.net.BindException: Address already in use indica que um processo órfão está ocupando a porta.
- Pare o agente e finalize quaisquer processos Jitterbit restantes antes de reiniciá-lo. Com o agente parado, verifique por processos perdidos: no Linux, execute ps aux | grep -E 'tomcat|jitterbit' e kill quaisquer IDs de processo restantes; no Windows, finalize quaisquer processos Jitterbit ou Tomcat perdidos no Gerenciador de Tarefas. Inicie o agente novamente assim que não houver mais processos.
- 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 estiver ficando sem memória, aumente a memória disponível (ou o limite de memória do contêiner). Veja 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 pode fazer com que os serviços falhem a cada reinício. Veja Espaço em disco e acumulação de logs.
- Se os logs mostrarem que o Process Engine está falhando em uma operação específica, entre em contato com suporte Jitterbit com os detalhes da operação e os logs do agente.
- Se a observabilidade nativa estiver habilitada, abra a aba Métricas da página Agentes do Console de Gerenciamento e revise os gráficos de serviço Tomcat e Process Engine para identificar quando os serviços começaram a falhar.

Operações expirando ou ignorando configurações de timeout

Sintoma: Operações são executadas indefinidamente ou por mais tempo do que o esperado. Para operações acionadas por API, as configurações de tempo limite configuradas no Studio parecem não ter efeito, e as operações podem permanecer presas em um status de Executando.
Causas possíveis:
- Por padrão, operações acionadas por APIs do API Manager ignoram as configurações de tempo limite de operação do Studio. A configuração EnableAPITimeout em jitterbit.conf deve ser explicitamente habilitada para que as operações de API respeitem os valores de tempo limite.
- Nenhum tempo máximo de execução da 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 tempo limite de operação para operações acionadas por API, defina EnableAPITimeout=true na seção [Settings] do jitterbit.conf.
2. Para limitar o tempo total de execução de qualquer operação, defina MaxOperationRuntimeSeconds na seção [ProcessEngine] do jitterbit.conf. Isso requer que RunOperationsInSeparateProcess seja true (o padrão).
3. Reinicie os serviços do agente após fazer alterações no 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 capacidade de processamento do agente não melhora.
Causas possíveis:
- Apenas max.concurrent.requests foi alterado. A capacidade de processamento do agente também depende dos pools de threads do Tomcat e Apache e dos pools de conexão HTTP, portanto, aumentar essa única configuração sem escalar as outras em conjunto não produz ganho.
- O host do agente não possui CPU ou memória suficientes para a concorrência adicional, 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, escalando as configurações relacionadas ao pool de threads e ao pool de conexões em conjunto. Veja Desempenho e ajuste do agente.
- Confirme que o host do agente possui CPU e memória adequadas para a maior concorrência. Se o agente travar ou entrar em um estado incapaz sob carga, veja Loop de reinício 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 lentidã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.
Causa possível: A biblioteca de análise XML usada pelo agente foi atualizada na versão 11.45, e a versão atualizada analisa grandes dados XML mais lentamente. Isso afeta transformações que iteram sobre um grande array, porque o mapeamento percorre repetidamente os dados analisados.
Resolução:
- Revise os caminhos de mapeamento da transformação para a notação #. Se um caminho usar # para iterar sobre um array, mas apenas o primeiro elemento for necessário, remova o # e reimplante. Remover o # mapeia apenas o primeiro elemento, portanto, aplique isso apenas onde a iteração sobre o array completo não é necessária.
- 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 percorra 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 (.dmp e .mdmp mini-dumps, e arquivos hs_err_pid*.log) em <JITTERBIT_HOME>/Tomcat/temp (ou, em versões mais antigas, na 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.
Causas possíveis:
- O coletor de estatísticas de disco AgentStats do agente trava a JVM enquanto coleta 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, o 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 desativar 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 ser excluídos com segurança para recuperar 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 da Jitterbit para uma solução alternativa.

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

Sintoma: Você deseja mudar o método de autenticação do PostgreSQL empacotado em um agente privado Linux de MD5 para SCRAM-SHA-256, mas o agente continua a usar MD5.
Causas possíveis:
- MD5 é a criptografia de senha padrão para o PostgreSQL empacotado em agentes privados Linux. SCRAM-SHA-256 foi 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 agente Linux de 12.6 ou 12.7, o instalador solicita que você redefina a criptografia para MD5 ou mantenha SCRAM-SHA-256; veja Atualizar um agente Linux.
- Editar pg_hba.conf e postgresql.conf sozinhos não completa a troca. O PgBouncer também deve ser reconfigurado com o hash do verificador SCRAM, ou o agente falha ao iniciar.
Resolução: Para mudar um agente 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 é mais performático, então a troca é uma mudança deliberada e em várias etapas: o guia reconfigura o PostgreSQL empacotado, atualiza as senhas dos usuários e reconfigura o PgBouncer com o novo hash. Reconfigurar a instância empacotada é a maneira suportada de habilitar o SCRAM. Não substitua a instância empacotada pelo seu próprio servidor PostgreSQL para obter SCRAM: agentes que usam uma instância PostgreSQL diferente da empacotada 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 devido a 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:
```
O certificado para <your-domain.sandbox.my.salesforce.com> não corresponde a nenhum dos nomes alternativos do assunto: ...
```
Outros endpoints afetados incluem hosts que compartilham um único IP por trás de hospedagem virtual.
Causa: O handshake TLS não está incluindo a extensão SNI, então o servidor retorna um certificado padrão em vez do que corresponde ao 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. O SNI é enviado por padrão, então quando está ausente, algo está suprimindo ou removendo-o.
Resolução:
1. Confirme se o SNI é a causa. A partir do host do agente, compare o certificado retornado com e sem SNI:
```
openssl s_client -connect HOST:443 -servername HOST   # certificado quando SNI é enviado
openssl s_client -connect HOST:443                    # certificado quando SNI é omitido
```
  Se o primeiro retornar o certificado correto e o segundo retornar o incorreto, o SNI é a causa.
2. Verifique se o SNI está explicitamente desativado 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 o SNI). Reinicie os serviços do agente.
3. Se o 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 a partir de um grupo de agentes em nuvem, o SNI não é a causa. O certificado do servidor pode não listar o host em seus Nomes Alternativos do Assunto. Para o Salesforce, adicione a URL MyDomain do sandbox ao certificado do Salesforce, ou veja Incompatibilidade de Nome Alternativo do Assunto do Certificado (SAN).

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

Sintoma: As 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.
Solução: Use barras normais em todos os caminhos de arquivos de chave SSH em jitterbit.conf, mesmo no Windows (por exemplo, C:/jitterbit/keys/id_rsa). Veja [SSH].

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

Sintoma: As 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 reinício do agente. As configurações de chave SSH adicionadas ao jitterbit.conf local também podem parar de ter efeito após o reinício do agente.
```
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 do agente remoto está habilitada (está ativada por padrão), portanto, as configurações gerenciadas através da aba Configuração do Jitterbit no Console de Gerenciamento têm precedência. As configurações da chave SSH adicionadas apenas ao jitterbit.conf local podem não ter efeito ou podem não ser mantidas após a reinicialização do agente.
- As configurações da chave SSH (PrivateKeyFile, PrivateKeyPassphrase, PublicKeyFile) estão na seção errada. Versões mais recentes do agente analisam estritamente e ignoram as configurações SSH colocadas fora da seção [SSH] (por exemplo, sob [SSL]).
Resolução:
1. Se a configuração remota estiver habilitada, adicione as configurações da chave SSH lá: abra o painel de Detalhes do grupo de agentes para o grupo de agentes, selecione a aba Configuração do Jitterbit e adicione-as na seção SSH. Veja Configuração do Jitterbit.
2. Se o jitterbit.conf local for a fonte de configuração, confirme se as configurações da chave SSH estão colocadas sob [SSH] (não [SSL]).
3. Reinicie os serviços do agente.
4. Para solução de problemas adicionais de autenticação de chave SFTP (campos de senha, frase secreta, formato da chave), veja 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) têm sucesso, e conectar ao servidor que falha a partir da linha de comando do SO também tem sucesso.

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 novos que a biblioteca cURL incluída em versões mais antigas do agente não suporta. Servidores que ainda aceitam os algoritmos mais antigos continuam a funcionar, razão pela qual a mesma chave tem sucesso 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 do proxy falham com um erro de autenticação.
Causa: Versões modernas do JDK desativam a autenticação básica durante o tunelamento de proxy HTTPS por padrão. A propriedade da JVM jdk.http.auth.tunneling.disabledSchemes bloqueia a autenticação básica, a menos que explicitamente liberada.
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, veja Permitir autenticação básica durante o 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) ao lado de 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 possam alcançá-lo.
Causa: Agentes privados não requerem que portas de entrada sejam abertas, 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 com o Harmony via HTTPS (porta 443). Todo o tráfego do Harmony e do gateway para o agente é roteado de volta por meio dessa 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 através do WebSocket de saída existente. O agente roteia a carga útil da 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 de múltiplos gateways).
Resolução:
- Abra o HTTPS de saída (porta 443) do host do agente para os 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, adicione à 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. Veja Portas de rede.
- Se um gateway de API privado estiver implantado, também permita a conectividade de saída de cada host de agente para o gateway (diretamente ou através do balanceador de carga em uma implantação de múltiplos gateways). O agente se conecta ao gateway para retornar a carga útil da resposta da API. Para o fluxo completo de requisição, veja Arquitetura do sistema do gateway de API privado.

API customizada 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 uma carga útil de requisição ou resposta (cabeçalhos mais corpo, comprimido) excede aproximadamente 1 KB, o gateway de API em nuvem Jitterbit estágios a carga útil, e o agente privado faz uma conexão de saída para o host jitterbitsysservice de sua região para baixar a carga útil da requisição (ou fazer upload da carga útil da resposta) antes de concluir a operação. Se o host do agente não conseguir acessar 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 padrão de conexão do agente 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 para 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. Veja Informações sobre a lista de permissões do Jitterbit para os URLs e IPs específicos da região.
2. Verifique a conectividade executando um teste HTTP do host do agente para o URL jitterbitsysservice de sua região, e então confirme que a API não expira mais.

Observabilidade nativa não mostrando dados

Sintoma: Após habilitar 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 vários minutos de espera.
Causas possíveis:
- 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 na configuração.
- O host do agente não consegue acessar a nuvem Harmony, impedindo o envio de métricas.
- O serviço de métricas está configurado para se conectar à instância PgBouncer embutida do agente privado em uma porta diferente da que o PgBouncer está realmente usando, de modo que o serviço de métricas não consegue se conectar a ele e as métricas são coletadas apenas parcialmente. Essa incompatibilidade de porta pode ocorrer após certas instalações ou atualizações do agente.
- Antes da versão 12.9 do agente, instalar um agente privado como um usuário não-root no Linux não provisionava o PgBouncer, então o serviço nunca começou e seu status sempre aparece como não saudável.
Resolução:
- Verifique se jitterbit.conf contém todas as configurações necessárias das seções [AgentMetrics] e [AgentCapability]. Veja o exemplo completo de configuração 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 na configuração foi feita.
- Verifique se o host do agente consegue acessar a nuvem Harmony. Veja Agente offline ou inacessível. Se o agente se conectar através de um proxy, veja Métricas do agente ausentes quando o agente se conecta através de um proxy HTTP.
- Se as métricas forem coletadas apenas parcialmente e os passos acima não resolverem, entre em contato com o suporte da Jitterbit para verificar se a porta de conexão do PgBouncer do serviço de métricas corresponde à porta configurada do PgBouncer.
- Para um novo agente privado Linux não-root, use a versão 12.9 ou posterior, onde o PgBouncer é corretamente provisionado 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 via HTTPS usando uma conexão separada que não herda a configuração do 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 em si se conecte com sucesso.
Resolução:
1. Confirme se o proxy suporta HTTPS. As métricas do agente são enviadas via HTTPS, portanto, um proxy que lida apenas com tráfego HTTP as bloqueia. Habilitar HTTPS no proxy resolve o problema.
2. Se você não puder habilitar HTTPS no proxy, ou se as métricas ainda estiverem ausentes após habilitá-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 da 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 do 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 reiniciar um host de agente privado Linux, os serviços do agente falham ao iniciar. Executar sudo jitterbit status mostra que o agendador e outros serviços não estão em execução, e os logs do agente (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 do PostgreSQL incluído são muito permissivas. O PostgreSQL requer que o diretório de dados seja 700 (apenas proprietário). Se as permissões forem mais frouxas (por exemplo, 755 ou 777), o PostgreSQL se recusa a iniciar, o que impede o restante do agente de iniciar.
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 do PostgreSQL como 700:
```
sudo chmod 700 /opt/jitterbit/DataInterchange/pgsql/data
```
3. Inicie os serviços do agente:
```
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 agente privado Linux para um novo host (ou realizar uma instalação limpa), os serviços do agente falham ao iniciar. O postgresql.log mostra:
```
[FATAL] password authentication failed for user "jitterbit"
```
O log do agente mostra que não consegue se conectar ao banco de dados. A falha persiste mesmo após desinstalação e reinstalação completas.
Causa: Um antivírus baseado em host ou produto de proteção de endpoint detecta o binário PgBouncer incluído como suspeito e o remove ou coloca em quarentena. Sem o PgBouncer, o agente não consegue se autenticar em seu banco de dados PostgreSQL interno.
Resolução:
1. Desative temporariamente o antivírus ou produto de proteção de endpoint no host do agente.
2. Adicione o diretório de instalação do Jitterbit (tipicamente /opt/jitterbit) à lista de exclusões do antivírus.
3. Reinstale o agente. No RHEL/CentOS:
```
sudo dnf reinstall jitterbit-agent
```
4. Inicie os serviços do agente e confirme a operação normal, em seguida, 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 agente privado sinaliza arquivos como log4j-over-slf4j-1.7.21.jar como uma vulnerabilidade do Log4j 1.x em fim de vida.
Resolução: Nenhuma ação é necessária. log4j-over-slf4j.jar não é Log4j 1.x. Ele faz parte da estrutura de registro SLF4J e atua como uma ponte que redireciona chamadas de bibliotecas de terceiros escritas contra a API Log4j 1.x para a estrutura de registro atual e suportada do agente. O arquivo não contém o código vulnerável do Log4j 1.x. Sua presença é a mitigação do agente contra a exposição ao 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 usando o Serviço de escuta falham com:

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

Causas possíveis:
- Poucos agentes no grupo de agentes estão em execução e conectados ao 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 se reconectar, reduzindo o número de agentes em execução e conectados abaixo do necessário $(N / 2) + 1$.
- Uma interrupção na rede dividiu o grupo de agentes em múltiplos clusters menores. Por exemplo, em um grupo de 4 agentes, uma divisão na rede pode produzir dois clusters de 2 agentes cada; nenhum atende ao requisito de $(N / 2) + 1$ de 3, então ambos relatam o erro, mesmo que todos os agentes estejam em execução.
Resolução:
- Confirme que $(N / 2) + 1$ dos agentes no 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 ou não. Por exemplo, um grupo de 4 agentes requer 3, e um grupo de 5 agentes também requer 3. Para ver quais agentes se juntaram, 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 estiver fora do ar e as mensagens permanecerem não processadas com a persistência habilitada, restaure o cluster manualmente. Veja Restauração do 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 na rede pode deixar o grupo dividido em duas metades, nenhuma das quais é grande o suficiente para manter o cluster em funcionamento.

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, fazendo com que operações dependentes não sejam executadas.
Resolução: Para estender a janela de retenção ou evitar 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, os logs da operação são gerados apenas quando a operação não é bem-sucedida. Operações de API personalizadas bem-sucedidas não produzem entrada de log por padrão.
Resolução: Para capturar logs para operações de API personalizadas bem-sucedidas, ative o registro de depuração de operações para a operação. Observe que o API Manager possui sua própria visualização de registro separada para solicitações de API.

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

Sintoma: O registro de depuração da operação foi ativado com uma data de término futura, mas os logs param de ser gerados antes que essa data seja alcançada.
Causa: Em grupos de agentes na nuvem, a data de término da configuração de registro de depuração da operação é não confiável. Os logs podem parar de ser gerados antes que o período de tempo configurado termine.
Resolução: Reative o registro de depuração da 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 tem registro de depuração da 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 correspondentes .input e .output estão ausentes.
Possíveis causas:
- O serviço de limpeza do agente está excluindo arquivos .input e .output antes que possam ser revisados.
- O agente reiniciou enquanto a operação ainda estava em execução, então os arquivos nunca foram escritos até a conclusão. Veja Dados de entrada/saída do 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. Encontre a regra de limpeza para o diretório DataInterchange/Temp/Debug e aumente o valor de <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 registro de depuração da 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 reiniciar todo o agente:

jitterbit stop verboselogshipper
jitterbit start verboselogshipper

No Windows e no 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 as 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 as 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 intermediário 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 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 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 é o 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 monitor 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 vir acompanhado de 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 do instalador .dmg.
3. Arraste o ícone do Jitterbit Studio para o atalho da pasta Applications na janela do instalador.
4. Inicie o Design Studio na pasta Applications (ou no Spotlight/Launchpad), não na 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:

Can not find target node (/PRESCRIPT/).
The structure may have changed so try to open the transformation 'example' and refresh the structure trees.

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 compartilhamentos 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 as URLs de endpoint, scripts e notas para caracteres invisíveis ou incomuns e remova-os ou substitua-os. O número da linha na mensagem de erro pode ajudar a localizar a área afetada no XML exportado.
3. Salve e implante o projeto corrigido e 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 de exportação do projeto .json 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: A importação ou abertura de 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 um lançamento 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 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 do seu Design Studio instalado e copie os valores required_version e requires-version dos arquivos desse projeto.
  4. Comprima os arquivos extraídos de volta em um arquivo .zip, renomeie para .jpk e importe-o.
  Essas etapas corrigem apenas o arquivo .jpk que você edita. Reexportar 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 no 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 reexportar o projeto com uma versão anterior afetada posteriormente pode escrever o requisito de versão incorreto de volta ao 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 em vez disso.
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, delete 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 Delete.

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

Sintoma: Uma fonte 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 para 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 Passive Mode está habilitado na configuração da fonte FTP (está habilitado por padrão).
- Trabalhe com seu administrador de rede para abrir o intervalo de portas altas usado pelo seu 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 resolver para locais inesperados.
Possíveis causas:
- Os campos de caminho da pasta de sucesso e pasta de erro em uma fonte 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 é mais amplamente suportado em servidores FTP.
- Alternativamente, 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 é funcional 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 depender dele 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: Testar uma conexão de fonte HTTP falha com um erro de conexão ou autorização, mas o endpoint é 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 sejam bem-sucedidas.
Resolução:
1. Se o endpoint for 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 melhor 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 deveriam estar 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: 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 com agendamento rápido 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 o agendamento 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 os IDocs devem ser processados em uma ordem garantida, ou sem aguardar a próxima execução agendada do agente de armazenamento, 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 aplicam 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 de armazenamento e encaminhamento: 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 direto, se o endpoint de destino estiver inacessível quando o IDoc for processado, a carga útil não será entregue e será perdida permanentemente. Não há mecanismo de repetição automática no processamento direto.
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 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 ao 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 os arquivos antes de expirarem.
- Como alternativa, 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 erros, 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 (Sucesso). Se o BAPI retornar um tipo de resposta I (Informação), E (Erro) ou W (Aviso), 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 personalizado, 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 que os IDocs de saída foram 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 nome do host 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 seu 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 por 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 Custom API URLs used e Proxy API URLs used, mostradas 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 Customer Success Manager.

API publicada retorna 404 Não encontrado

Sintoma: Chamar uma API publicada retorna um erro 404.
Possíveis causas:
- O limite de Hits 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 Hits 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: 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 solicitaçã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 grandes payloads ou lógica de transformação complexa.
- A solicitaçã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 desse caso é que a solicitaçã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 for causado por um backend lento, revise a operação e sua lógica de transformação para identificar gargalos de desempenho, particularmente grandes payloads de dados ou chamadas externas lentas, e reduza a etapa lenta.
- Se a operação realmente 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á habilitada 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 correlacionarem 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 o desempenho dos agentes privados Jitterbit.

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

Sintoma: O API Portal exibe nomes ou atributos de projeto desatualizados após um projeto ser renomeado ou atualizado.
Possível causa: O API Portal 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 a guia Documentation na página APIs e clique em Save & Publish.
2. Verifique se as informações atualizadas aparecem corretamente no API Portal.

Microsoft Entra ID OAuth: O 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 "Nova 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 ao 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 security profiles 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 solicitaçõ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 solicitaçã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 solicitaçã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.

401 Não autorizado com uma lista de permissões de IP válida (cache obsoleto)

Sintoma: As chamadas da API retornam 401 Unauthorized 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 Trusted IP Groups, 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 Trust requests only from the following IP ranges em um perfil que ainda usa intervalos de IP legados remove permanentemente esses intervalos (um prompt de confirmação avisa sobre isso), portanto, migre os IPs para um grupo de IP confiável em vez de desativar a configuração para limpar o cache.

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

Sintoma: O gateway de API retorna:
```
414 URI Too Large
```
Possível causa: A URL do serviço construída (incluindo URL base, caminho do serviço e quaisquer parâmetros de caminho ou consulta) excede 8.000 caracteres.
Resolução:
- Reduza o comprimento da URL do serviço encurtando o caminho do serviço ou dividindo a API em múltiplos 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: Configurar um caminho de serviço de API proxy com parâmetros de caminho (por exemplo, /resource/{id}) falha quando inserido manualmente, porque o campo não aceita caracteres de chaves.
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 API Manager

Sintoma: Excluir uma API no API Manager falha: a interface mostra 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 de Admin. Excluir uma API primeiro verifica quais Grupos de API a API está associada e visualizar a página Grupos de API requer a permissão de 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 de Admin que execute a exclusão. Conceder à função afetada a permissão de 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 da 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 de APIs e selecione o ambiente correto durante a clonagem.
- Como alternativa, exporte a API do seu ambiente atual e importe-a no 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 requisiçõ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 requisições de preflight do navegador, mas significa que qualquer requisiçã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. Este é 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 requisiçõ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 em 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 em nuvem, a API sendo proxificada deve ser 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 em nuvem.
Resolução:
- Confirme que a API de destino é acessível pela internet pública, mesmo que esteja protegida.
- Se a API de destino deve permanecer atrás de um firewall, implante um gateway de API privado na mesma rede privada em vez de usar o gateway de API em nuvem.
- Para adicionar os endereços IP do gateway em nuvem à lista de permissões para que o gateway possa acessar a API proxificada, consulte Informações de lista de permissões.

A configuração Mostrar cargas 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 é 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 personalizada 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 "verificar Jitterbit Services" sem entrada de log da 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 tem 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 têm CPU e memória suficientes.
2. Monitore o uso de threads de trabalho Apache dos agentes. Se a observabilidade nativa estiver habilitada, 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 no 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: Os perfis de segurança são armazenados em cache no gateway de API. As 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 API Portal.
Possível causa: A documentação do API Portal 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á.
- Como alternativa, use a guia 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 excluir um perfil de segurança falha ou a opção de exclusão não está disponível, mesmo após desatribuir o perfil de uma API.
Possível causa: Após remover um perfil de segurança da configuração de uma API, a API deve ser salva e republicada 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 desatribuir o perfil de segurança da API, clique em Save e depois em Publish na API.
2. Após a API ser republicada com a configuração atualizada, o perfil de segurança não será mais exibido como em uso e poderá ser excluído.

OAuth de 2 pernas retorna para 3 pernas 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 quando servido por um gateway de API privado.
Possível causa: Os 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 com múltiplos gateways: 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 contêineres do gateway devem ser executados no mesmo host. Contêineres implantados em hosts diferentes não conseguem coordenar a recuperação de payload, causando falhas intermitentes.
Resolução:
1. Confirme que todos os contêineres do gateway de API privado no grupo estão sendo executados no mesmo host físico ou virtual.
2. Se os contêineres 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 TLS padrão.
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 personalizadas 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 "Arquivo ou diretório não encontrado"

Sintoma: Os 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 significa necessariamente 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 acontecer 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 teste novamente 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 de carga roteia cada solicitação e sua resposta consistentemente para o mesmo nó, porque os arquivos de payload e resposta hospedados são locais para o nó que os criou. Para gateways containerizados, consulte ALB multi-gateway: Todos os contêineres devem estar no mesmo 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 exigem os pacotes geoip-devel e libGeoIP, fornecidos pelo repositório EPEL. A instalação documentada habilita 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 acessar o EPEL para baixar os pacotes.
Resolução:
- Em um host de gateway com acesso à internet, habilite o repositório EPEL antes de instalar o gateway, conforme descrito em Instalar um gateway de API privado: execute yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm e 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 "Falha, chamada de teste para API falhou"

Sintoma: O utilitário de autoteste de 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 (Nome do Serviço e Caminho), causando falha na chamada de teste.
Resolução:
- Atualize o gateway de API privado para a versão 11.31 ou posterior, o que resolve isso automaticamente.
- Se não for possível atualizar imediatamente: abra a configuração de API da API chamada ApiGatewayTest, preencha o campo Nome do Serviço com qualquer valor (por exemplo, service), defina Caminho 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 do 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: APIs de proxy têm uma configuração disable-hyphen-replacement que controla se hífens em nomes de 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 de API de proxy, verifique a configuração de cabeçalho disable-hyphen-replacement. Para preservar hífens em nomes de 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 acionada pela API. As 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. As operações malsucedidas sempre são registradas; apenas os logs de operação bem-sucedidos e qualquer saída de WriteToOperationLog de execuções bem-sucedidas ficam ocultos. As 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 os logs de operação bem-sucedidos e a 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 os payloads, ative Ativar modo de depuração até (como na etapa 1) ou combine Log de depuração de operação com Mostrar payloads de solicitação e resposta nos 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.

Carga da API disponível no agente por 2 dias

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

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

Sintoma: A página Logs da API não mostra as entradas de log esperadas, mesmo que a API esteja sendo executada com sucesso.
Possível causa: A página Logs da 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 da 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 menu suspenso 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 da API em vez disso. Os dados de log permanecem disponíveis lá, mas não podem ser filtrados por nome de API.

Erro 429: limite mensal de acessos à 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 pela 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 é reiniciado 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 Gerente de Sucesso do Cliente.

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

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 ou intervalo de endereços do consumidor 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 solicitações de API por minuto por organização, compartilhado entre todos os tipos de API (personalizada, proxy e OData). Este limite não se aplica a gateways de API privados.
Resolução:
- Revise 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 solicitaçõ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 re-assinados 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.
- Revise 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 funcionalidade EDI do Harmony: comunicação com parceiros comerciais e processamento de documentos EDI.

Falha na conexão AS2 ou no 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 na 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 EDI Jitterbit 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. As 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 no Jitterbit EDI, entre em contato com o suporte Jitterbit ou com 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 ou elemento de dados obrigatório 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: Analise 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, depois, 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 EDI ou schema

Sintoma: Documentos EDI são gerados com conteúdo incorreto, campos ausentes ou uma estrutura inesperada, ou documentos de entrada falham no processamento.
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. Analise as configurações EDI do parceiro comercial afetado em Configurações 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 suas confirmações 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 está enviando para o endpoint correto.

AS2: o firewall do parceiro comercial deve permitir os 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 EDI Jitterbit.
Resolução:
- Forneça os seguintes endereços IP do EDI Jitterbit 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 este 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 da 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 Console de Gerenciamento.
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, então 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 do Conector estiver habilitada, atualize o conector do grupo de agentes na página Agentes do Console de Gerenciamento.

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

Adição de 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 atualmente atribuída a um parceiro comercial deve ser desatribuída antes de poder ser removida.
Resolução:
1. Em 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óxima Hora de Execução" não é atualizado 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 consulta o 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.

Falha na adição de ID EDI ou ID Preferido: 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 as configurações de PII (informações de identificação pessoal) para um parceiro comercial está indisponível ou desativada.
Possível causa: Ativar as configurações de PII requer a permissão Admin permission. Nem a função EDI User nem a EDI Viewer podem ativar as 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 as configurações de PII regularmente, atualize a atribuição de função de acordo.

Desenvolvimento de aplicativos

Esta seção aborda problemas com a funcionalidade de desenvolvimento de aplicativos do Harmony: criação, implantação e execução de 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 um 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.

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

O App Builder não inicia automaticamente após uma 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: A licença do App Builder 4.x não pode ser enviada 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.

O 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ção 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 ao preencher a 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.

Conector do App Builder: A 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.

Conector do App Builder: 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 aplicação 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 app 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.

Usuário não consegue acessar 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.

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

App offline: Banco de dados local é apagado quando o app é 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.

App offline: Agendamentos em segundo plano não são executados quando o app 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.

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

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

507 Armazenamento insuficiente

502 Bad Gateway

Falha ao criar diretório temporário

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

Log de depuração de operação expõe PII e credenciais em texto simples

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

Falha ao carregar certificado de cliente em agentes privados Linux

Erros de validação de operação

Nomes de componentes devem ser exclusivos após importação de projeto

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

Nó de loop de destino mapeado para vários nós de loop de origem

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

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

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

Aviso de subelemento extra nos logs de operação

Limite de iteração de loop de script excedido

Comparar uma string com um número produz resultados inesperados

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

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

Campos mapeados em branco com esquemas de origem simples

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

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

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

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

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

Saída de transformação JSON omite campos null e string vazio

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

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

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

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

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 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 string vazio

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

`IsNull` retorna false para strings vazias de dados de origem JSON

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

Espaço de heap Java: `OutOfMemoryError`

Falhas de conexão com `TranDb`

Apache: Nenhum `ConfigArgs` instalado

Apache/Tomcat: `APPARENT DEADLOCK`

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

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

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

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

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