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

Introdução

Se você encontrar problemas ao executar uma operação, as seguintes ações de solução de problemas são recomendadas.

Testar a conexão

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

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

Verificar os logs da operação

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

Dependendo do tipo de agente, você pode recuperar arquivos de log e dados adicionais:

• Ativar o registro de depuração da operação (para agentes em nuvem ou para agentes privados).
• Ativar o registro detalhado do conector (apenas agentes privados).
• Verificar os logs do agente (apenas agentes privados).

Possíveis erros nos logs da operação

As seções a seguir abordam erros que podem estar presentes em um log de operação e suas resoluções.

Uma dependência de arquivo não foi encontrada

O erro Uma dependência de arquivo não foi encontrada pode ter várias causas. Uma possível causa é que os agentes privados fiquem fora de sincronia com a nuvem Harmony, resultando no agente privado não recebendo arquivos (como esquemas) que deveria receber. Esse problema de sincronização pode fazer com que as operações falhem quando o agente não consegue acessar as dependências necessárias.

Embora esse problema geralmente se resolva por conta própria, você pode acionar manualmente uma re-sincronização do ambiente para resolver a questão:

1. Use o programa utilitário JitterbitUtils do agente privado.
2. Execute a opção --resync-environment ENVIRONMENT no servidor do agente (substitua ENVIRONMENT pelo nome do seu ambiente).

Esse processo força o agente a re-sincronizar com a nuvem Harmony e baixar quaisquer arquivos ou dependências ausentes.

Para mais informações sobre sincronização de ambientes, veja Ajuste de desempenho de sincronização de ambientes.

Aviso de subelemento extra

Um aviso de subelemento extra nas mensagens de log pode geralmente ser ignorado. Esse aviso indica que a carga útil da API de um conector retornou mais nós ou campos de dados do que os definidos no esquema de dados da resposta.

Caracteres não permitidos em mapeamentos de esquema XML

Dependendo da atividade do conector, esses caracteres são inválidos e resultarão em um erro em tempo de execução:

Quando os dados de entrada ou saída fornecidos a ou retornados de uma transformação adjacente a uma atividade de conector baseada em XML contêm um dos caracteres acima, um erro específico referenciando esse caractere é retornado em tempo de execução. Por exemplo, quando o caractere de controle \x1E está presente na transformação de resposta para a atividade Get BAQ do Epicor Kinetic, esse erro é retornado em tempo de execução:

A exceção é caractere de espaço em branco inválido (0x1e) no texto a ser enviado

Elementos XML não suportados quando incorporados em JSON

As seções de dados de caractere (CDATA) não são suportadas com XML incorporado em JSON destinado a ser enviado através de uma transformação. Incluir seções CDATA pode causar o seguinte erro a aparecer em um log de operação em tempo de execução:

Transformação falhou. Erro: A operação "Operação" falhou.
Erro: Falha ao converter arquivo XML para JSON.
org.jitterbit.integration.server.engine.EngineSessionException: org.xml.sax.SAXParseException ...

Para contornar isso, use um script Jitterbit para Substituir os caracteres &, <, >, ' e " de toda a seção CDATA, incluindo sua definição (<![CDATA[ ... ]]>), por &amp, &lt, &gt, &apos, &quot respectivamente. Se necessário, a string XML inteira contendo a seção CDATA pode ser substituída se o direcionamento da seção não se adequar ao seu caso de uso.

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

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

Reprocessamento de esquemas XML espelhados

Devido a mudanças feitas nas versões do Harmony 10.25 e 10.27, você pode observar comportamentos diferentes em projetos criados antes dessas versões. Essas mudanças afetam esquemas XML que foram espelhados e provavelmente impactarão mapeamentos que utilizam funções XML que envolvem namespaces, como a função SelectNodes. Nesse caso, mapeamentos que eram válidos anteriormente podem agora ser inválidos com um erro relacionado à sintaxe da função XML.

Compare as diferenças entre este exemplo de esquema XML espelhado antes de 10.25 com um criado em 10.25 ou posterior:

• Exemplo de Esquema XML Antes de 10.25: Em projetos criados antes de 10.25, esquemas XML espelhados usam o prefixo de namespace padrão para documentos XML: xsi. Como mostrado destacado em vermelho acima, xmlns:xsi declara o namespace e campos não mapeados são exibidos no esquema com o atributo xsi:nil="true".
• Exemplo de Esquema XML em 10.25 e Posteriores: Em projetos criados em 10.25 e posteriores e destacados em verde acima, esquemas XML espelhados usam o prefixo de namespace ns para declarar um namespace qualificado. Campos não mapeados não são exibidos no esquema.

Nas versões 10.25 e 10.26, se você importou um projeto com um esquema XML espelhado que foi criado antes de 10.25, o esquema foi reprocessado e alterado para usar o prefixo de namespace qualificado.

A partir da versão 10.27, projetos importados cujos esquemas XML espelhados foram criados antes de 10.25 mantêm o prefixo de namespace padrão do esquema XML, de modo que o esquema é idêntico ao que era quando foi criado. Essa mudança significa que qualquer projeto anterior a 10.25 que for importado para a versão atual deve funcionar como originalmente projetado.

Para forçar uma atualização de um esquema XML anterior à versão 10.25 para usar o prefixo de namespace atualizado, você pode regenerar o esquema atualizando-o ou reconfigurando a atividade que fornece o esquema.

Caracteres especiais em esquemas JSON fornecidos por conectores

Quando uma transformação utiliza um esquema JSON herdado de uma atividade de conector adjacente, quaisquer caracteres especiais em um campo ou nome de nó do esquema são substituídos por sublinhados (_).

Ao usar o processamento JSON legado (o padrão para projetos criados antes do lançamento 11.48 Harmony), esse comportamento pode causar erros retornados do endpoint.

Por exemplo, se a atividade fornecer um nome de campo location_ids[], ele será convertido para location_ids__, no entanto, o endpoint ainda espera o nome de campo original location_ids[] e retorna um erro, como "error_message": "{location_ids:expected String to be a Array}",}}.

Para resolver esse problema, siga estas etapas:

1. Confirme que um esquema JSON está sendo usado na atividade afetada. Esses esquemas terão um nó raiz chamado json:

   

2. Configure o projeto para usar o Processamento de nomes JSON preservados ativando a configuração de Preservar nomes JSON configuração do projeto (é necessário ter a versão do agente 11.48 ou posterior).

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

   Importante

   Quando Preservar nomes JSON é ativado em um projeto onde está atualmente desativado, observe que o Processamento de nomes JSON preservados será usado apenas para operações e esquemas configurados após a ativação da configuração. Ou seja, operações e esquemas existentes continuarão usando o processamento JSON legado. Recomendamos reconfigurar todas as operações e esquemas existentes em tais projetos, pois usar ambos os métodos de processamento de esquema em um único projeto pode causar inconsistências no projeto.

Ao usar o processamento Preserve JSON names, você pode verificar o nome do campo ou nó que está sendo passado para o endpoint visualizando o jsonPropertyName nos dados de entrada ou saída da atividade quando o registro de depuração está habilitado (para agentes em nuvem ou para agentes privados). O valor do jsonPropertyName é o valor que está sendo enviado na solicitação: