Solução de problemas de tempo de execução de operações no Jitterbit 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 em Connector SDK implantados em operações 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:

• Ative o registro de depuração da operação (para agentes em nuvem ou para agentes privados).
• Ative o registro detalhado do conector (apenas agentes privados).
• Verifique 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 a sincronização de ambientes, veja Ajuste de desempenho da 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 \x1E caractere de controle está presente na transformação de resposta para a atividade Get BAQ do Epicor Kinetic, este 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:

A 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, toda a string XML contendo a seção CDATA pode ser substituída se o direcionamento da seção não se encaixar no 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>"
}

Esquemas espelhados com grupos de substituição

Esquemas espelhados que utilizam grupos de substituição não são suportados. Usar um esquema espelhado que possui grupos de substituição resultará em um erro de tempo de execução da operação:

Falha ao inicializar a transformação "<nome da transformação>". Falha ao expandir a árvore (source|target) para o caminho: <caminho para o nó cabeça de substituição>.

Esse erro também pode ocorrer por outros motivos e não indica necessariamente que o problema está em um esquema espelhado que possui grupos de substituição. Se o erro for aplicável ao seu esquema, recomendamos limpar o esquema espelhado e recriá-lo de outra forma (fazendo upload, criando um esquema personalizado, etc.).

Reprocessamento de esquemas XML espelhados

Devido a mudanças feitas nas versões do Harmony 10.25 e 10.27, você pode observar um comportamento diferente 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 anteriormente válidos 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 utilizam 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 utilizam o prefixo de namespace ns para declarar um namespace qualificado. Campos não mapeados não são exibidos no esquema.

Em versões 10.25 e 10.26, se você importou um projeto com um esquema XML espelhado que foi criado antes da 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 da 10.25 mantêm o prefixo de namespace XML padrão, de modo que o esquema é idêntico ao que era quando foi criado. Essa mudança significa que qualquer projeto anterior à 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 à 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 usa um esquema JSON herdado de uma atividade de conector adjacente, quaisquer caracteres especiais em um campo ou nome de nó do esquema são substituídos por sublinhados (_).

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

Por exemplo, se a atividade fornece um nome de campo location_ids[], ele é 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 projeto Preserve JSON names (é necessária a versão do agente 11.48 ou posterior).

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

   Importante

   Quando Preserve JSON names está ativado em um projeto onde atualmente está desativado, observe que o processamento Preserve JSON names será utilizado apenas para operações e esquemas configurados após a ativação da configuração. Ou seja, operações e esquemas existentes continuarão utilizando 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 esquemas 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á ativado (para agentes em nuvem ou para agentes privados). O valor do jsonPropertyName é o valor que está sendo enviado na solicitação: