Conector NetSuite avançado no Jitterbit Design Studio

Introdução

Esta página cobre dicas de solução de problemas, tutoriais e funcionalidades avançadas relacionadas a integrações com o NetSuite.

Solução de problemas e tutoriais

Esta seção descreve problemas e soluções para questões comuns enfrentadas em integrações com o NetSuite e fornece informações sobre mudanças no NetSuite que podem afetar sua integração.

URL WSDL específica da conta do NetSuite

Durante a configuração de um endpoint do NetSuite, é necessário fornecer uma URL WSDL específica da conta no campo URL de Download WSDL. Esta seção mostra como obter essa URL encontrando o domínio específico da conta do NetSuite e, em seguida, usando o domínio específico da conta na URL WSDL.

Encontrando o domínio específico da conta do NetSuite

Essas etapas devem ser realizadas por um Administrador do NetSuite ou outro usuário com a permissão Configurar Empresa:

1. Faça login na instância do NetSuite.

2. Vá para Configuração > Empresa > Informações da Empresa (ou pesquise por Informações da Empresa).

3. Na página Informações da Empresa, vá para a subaba URLs da Empresa. O domínio específico da conta está sob o cabeçalho SuiteTalk (Serviços Web SOAP e REST):

   

Para mais informações, consulte URLs para Domínios Específicos de Conta.

Construindo a URL WSDL

Depois de obter o domínio específico da conta, use-o para construir a URL WSDL:

• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2024_2_0/netsuite.wsdl
• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2024_1_0/netsuite.wsdl
• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2023_2_0/netsuite.wsdl
• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2023_1_0/netsuite.wsdl
• https://abcdef123456.suitetalk.api.netsuite.com/wsdl/v2022_2_0/netsuite.wsdl

Durante a configuração de um endpoint do NetSuite, insira esta URL WSDL específica da conta no campo URL de Download do WSDL.

Informações sobre quais versões do agente Jitterbit são necessárias para uso com as versões WSDL acima estão disponíveis em Pré-requisitos na página do endpoint do conector do NetSuite.

Alterar a versão do WSDL

Atualizar periodicamente a versão do WSDL utilizada pelo seu endpoint do NetSuite, a fim de sempre usar uma versão totalmente suportada, é uma boa prática recomendada. Os passos abaixo descrevem a melhor maneira de fazer a alteração, garantindo uma atualização sem problemas.

1. Crie um novo endpoint.

2. Para cada operação do NetSuite, troque o endpoint antigo pelo novo.

3. Atualize a função.

4. Atualize as transformações.

5. Repita os passos 2 a 4 para cada operação do NetSuite.

Erro do data center do NetSuite

Devido a mudanças feitas pelo NetSuite, alguns formatos de URL WSDL que eram anteriormente permitidos não são mais aceitos, incluindo URLs WSDL genéricas e URLs específicas de data center. O Jitterbit recomenda sempre usar uma URL WSDL específica da conta.

Um endpoint do NetSuite pode ter sido testado com sucesso anteriormente, mas agora falha com este erro:

Erro do Conector: Erro ao obter a URL do data center.

Causado por: org.jitterbit.integration.server.engine.connector.exception.NetSuiteWebServiceRuntimeException: FaultString:

Nesta conta, você deve usar domínios específicos da conta com este endpoint de serviços web SOAP. Você pode usar a operação SOAP getDataCenterUrls para obter o domínio correto. Ou, vá para Configuração > Empresa > Informações da Empresa na interface do usuário do NetSuite. Seus domínios estão listados na aba URLs da Empresa.

Em algumas circunstâncias, este erro pode aparecer:

Você não está solicitando o centro de dados correto para sua empresa.

Esses erros podem resultar do uso de uma URL de Download WSDL incorreta na configuração de uma conexão NetSuite. Devido a mudanças feitas pelo NetSuite, alguns formatos de URL WSDL que eram anteriormente permitidos não são mais aceitos, incluindo URLs WSDL genéricas e URLs específicas de centro de dados. Por exemplo:

• URL WSDL Genérica: https://webservices.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
• URL WSDL Específica de Centro de Dados: https://webservices.na3.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl

Para resolver, altere a URL 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 instruções sobre como encontrar o domínio específico da conta NetSuite e, em seguida, usar o domínio específico da conta na URL WSDL, veja URL WSDL específica da conta NetSuite.

Autenticação de dois fatores do NetSuite (TFA ou 2FA)

Aqueles que usam a autenticação de dois fatores do NetSuite (TFA ou 2FA) não devem usar o tipo de autenticação de login único (SSO) ao configurar seu endpoint do NetSuite no Jitterbit. Fazer isso pode causar a falha do seu endpoint do NetSuite. Em vez disso, recomenda-se que esses usuários habilitem a autenticação baseada em token (TBA) em sua conta NetSuite e configurem seu endpoint do NetSuite no Jitterbit de acordo.

URL WSDL do sandbox do NetSuite

Desde janeiro de 2018, o NetSuite usa a mesma URL para seus domínios de produção e sandbox. Para as versões 9.2 e superiores do Design Studio e do Agent, nenhuma ação é necessária para os usuários do Jitterbit com endpoints NetSuite existentes configurados para o domínio sandbox, desde que o sandbox tenha sido atualizado desde essa mudança.

O número da conta NetSuite agora é usado para determinar se a conta está em produção ou em sandbox. Por exemplo, o ID da conta pode ser acrescido de _SB1, _SB2, etc. Como o NetSuite não usa mais uma URL de sandbox separada, e o sandbox agora é indicado pelo ID da conta, a caixa de seleção Sandbox foi removida nas versões 9.2 e superiores do Design Studio.

Se o seu sandbox do NetSuite não foi atualizado desde que essas mudanças no NetSuite foram implementadas, pode ser necessário usar uma URL WSDL específica para sandbox.

Erro de permissões para TBA

Se você receber um erro INSUFFICIENT_PERMISSION ao executar operações usando um endpoint do NetSuite configurado com autenticação baseada em token (TBA), pode ser necessário usar um papel diferente para gerar os tokens de acesso ou adicionar permissões ao papel que você está usando atualmente. Nesse caso, o teste do endpoint parece bem-sucedido, mas durante a execução da operação ocorre a exceção.

Para resolver, ao gerar tokens de acesso, certifique-se de gerá-los em um papel de Acesso Total ou Administrador ou verifique se as permissões apropriadas estão permitidas para o papel.

Erro inesperado para TBA

Se você receber um erro UNEXPECTED_ERROR ao testar a conexão com um endpoint do NetSuite configurado com autenticação baseada em token (TBA), é recomendável verificar se você está usando a URL WSDL correta. O erro conterá o seguinte texto:

FaultString: Um erro inesperado ocorreu. O Suporte Técnico foi alertado sobre esse problema.

Este erro pode ocorrer por uma série de razões; no entanto, sabe-se que esse erro resulta de ter uma URL WSDL incorreta ao usar Agentes que estão na versão 9.2 a 9.5. Nos Agentes da versão 9.6 e superiores, o texto da mensagem de erro descreve o problema de forma mais precisa.

Governança de concorrência do NetSuite

Em 18 de agosto de 2017, o NetSuite introduziu a "Governança de Concorrência" em seu lançamento 2017.2. Se você usa serviços web e/ou RESTlets, saiba mais sobre como isso pode afetar sua integração em governança de concorrência do NetSuite 2017.2.

Limitações de pesquisa salva do NetSuite

Ao usar a pesquisa salva do NetSuite, se você estiver tentando pesquisar em objetos que têm mais de 1.000 pesquisas salvas, pode parecer no Jitterbit Studio que não há pesquisas salvas disponíveis no objeto. Nesse caso, o menu suspenso de pesquisa salva no Jitterbit Studio não será preenchido com nenhuma pesquisa salva. Isso se deve a um limite de 1.000 registros imposto pelo NetSuite em solicitações de API.

Confirmação da limitação

Para confirmar que o problema está na limitação do NetSuite, você pode verificar o Registro de Uso de Serviços Web dentro da sua instância do NetSuite. Para um erro desse tipo, o log terá uma entrada semelhante à seguinte:

<platformCore:code>MAX_RCRDS_EXCEEDED</platformCore:code>
<platformCore:message>O número máximo ( 1000 ) de registros permitidos para uma operação de LEITURA foi excedido.</platformCore:message>

Solução alternativa para a limitação

Como uma solução alternativa, recomenda-se limpar as pesquisas salvas do NetSuite que não estão mais sendo usadas para reduzir o número de pesquisas salvas para menos de 1.000. Após a redução do número de pesquisas, você poderá selecionar uma pesquisa salva no menu suspenso do Jitterbit Studio.

Uma alternativa para reduzir o número de pesquisas salvas é executar a pesquisa salva via SOAP, referenciando a pesquisa salva pelo ID. Observe que essa alternativa não utiliza o conector do NetSuite e pode resultar em problemas ao migrar ambientes.

Funcionalidade Avançada

Esta seção fornece informações sobre recursos no Jitterbit que permitem aproveitar mais a sua integração com o NetSuite.

Usando funções do NetSuite

As funções específicas do NetSuite disponíveis no Construtor de Fórmulas em Funções > Funções do Conector estão listadas abaixo. Para mais informações sobre como usar essas funções, consulte Funções do conector.

• NetSuiteGetSelectValue: Recupera os valores da lista de seleção para um campo do NetSuite.
• NetSuiteGetServerTime: Obtém a hora do servidor do NetSuite.
• NetSuiteLogin: Obtém a sessão do NetSuite.

Usando a configuração assíncrona

Por padrão, as chamadas de API para o NetSuite são executadas de forma síncrona; ou seja, após uma solicitação ser feita, a conexão é mantida aberta. Se algumas solicitações expirarem durante uma consulta síncrona, pode ser necessário ativar a configuração assíncrona. Com essa configuração, após a solicitação ser enviada, o Jitterbit fará consultas periodicamente para verificar se essa solicitação foi concluída. Isso é mais útil com grandes volumes de dados.

Para ativar a opção assíncrona, defina $jitterbit.netsuite.async=true em um script que esteja, por exemplo, no início da operação ou dentro da cadeia de operações (veja Criando um script). Para informações adicionais, consulte a documentação do NetSuite sobre Processamento de Solicitações Síncronas versus Assíncronas.

Passando valores nulos para campos personalizados

Uma limitação da API do NetSuite é que você não pode passar valores NULL ou em branco (string vazia) para campos personalizados no NetSuite.

De acordo com a documentação do NetSuite sobre CustomFieldList, campos personalizados podem ser definidos como NULL ao enviar o campo na nullFieldList do NetSuite.

No Design Studio, você não verá nullFieldList como um campo ou opção.

Em vez disso, você pode passar valores NULL ou em branco (string vazia) para campos personalizados mapeando o campo de origem para os campos externalId e name de um campo de destino.

Usando segmentos personalizados do NetSuite

Segmentos personalizados em objetos padrão e personalizados do NetSuite são suportados para o Conector do NetSuite nas atividades Criar, Atualizar, ObterLista, Upsert e Pesquisar usando um endpoint do NetSuite com um WSDL do NetSuite que é da versão 2016.2 ou superior. É necessário usar a versão 9.4 ou superior tanto do Design Studio quanto dos Agentes para utilizar este recurso.

Ao configurar qualquer um dos tipos de atividade listados acima, você verá cada segmento personalizado exibido na estrutura de resposta ou solicitação do NetSuite:

Uma vez que a atividade é utilizada em uma transformação, será possível mapear de ou para qualquer um desses segmentos personalizados, assim como se faz com outros campos. Os segmentos personalizados estão localizados sob um nó chamado customFieldList que está presente dentro do respectivo nó do objeto.

Limitação

Em uma pesquisa avançada do NetSuite, segmentos personalizados do tipo Lista/Registro conforme definido no NetSuite não são suportados. No entanto, observe que o tipo Seleção Múltipla é suportado em uma pesquisa avançada do NetSuite. Para determinar qual tipo está sendo utilizado, verifique o Tipo definido dentro do NetSuite em seu Segmento Personalizado:

Essa limitação não se aplica a outros tipos de atividades do NetSuite; ou seja, tanto os tipos List/Record quanto Multiple Select são suportados dentro das atividades Create, Update, GetList, Upsert, Basic search, Expanded search e Saved search.

Usando a pesquisa de transações do NetSuite por status

Ao pesquisar transações do NetSuite com base em um status específico, será necessário especificar o valor correto do filtro de pesquisa que corresponde ao status desejado. Você pode determinar o valor correspondente do filtro de pesquisa conforme fornecido na tabela abaixo.

Por exemplo, se você quiser que os critérios de pesquisa limitem os registros de Item Fulfilment apenas àqueles onde o Ship Status = Shipped, em vez de usar o enum para Shipped (_shipped), você realmente precisaria usar o valor ItemShip:C conforme fornecido na tabela abaixo. Traduções semelhantes se aplicam a uma variedade de objetos do NetSuite.

Fonte: http://blog.prolecto.com/2013/08/30/netsuite-searchfilter-transaction-internal-status-list/

Padrões de design

Os seguintes padrões de design podem ser úteis para integrações com o NetSuite:

• Capturando alterações de dados com uma API do Gerenciador de API ou ponto de extremidade HTTP

• Capturando alterações de dados com fontes de arquivo

• Capturando alterações de dados com valores de campo de origem

• Capturar alterações de dados com alterações de tabela ou arquivo

• Capturando alterações de dados com consultas baseadas em timestamp

• Criando saída de registro único ou múltiplo

• Criando iterador de transformação dinamicamente

• Melhores práticas do Harmony

• Vinculando registros de origem ou destino usando IDs compartilhados

• Buscando dados durante a execução

• Buscando dados usando um dicionário

• Persistindo dados para processamento posterior usando Armazenamento Temporário

• Persistindo dados de entrada para processamento posterior

• Processando registros de destino condicionalmente

• Executando próximas operações condicionalmente usando cadeias de operações

• Configurar um projeto de colaboração em equipe

• Configurar alertas, registro e tratamento de erros

• Atualizando múltiplos destinos a partir de um único registro de origem

• Upsertando dados do Clarizen com uma cadeia de operações