Conector NetSuite Upsert no Jitterbit Design Studio

A atividade de upsert do NetSuite disponível dentro do conector NetSuite permite atualizar registros existentes ou criar novos registros em uma instância do NetSuite conectada usando o Jitterbit. Um "upsert" é essencialmente uma operação de atualização ou criação, ou ambas, dependendo dos dados fornecidos.

Esta página descreve como atualizar registros existentes e criar novos registros do NetSuite ao mesmo tempo, usando um exemplo de atualização do número de telefone de um cliente existente e criação de um novo cliente no NetSuite a partir de dados de origem fornecidos em um arquivo CSV através do Jitterbit.

Este exemplo demonstra a criação de um novo cliente e a atualização das informações do cliente em um registro que foi criado como exemplo durante o walkthrough de criação do conector NetSuite. Este exemplo é utilizado apenas para fins de demonstração e não cobre todas as opções disponíveis no produto; consulte Design Studio para uma documentação mais abrangente.

As seções a seguir estão divididas em início da atividade de upsert, definição dos componentes da operação e implantação e execução da operação.

Criando uma operação Upsert do NetSuite

1. Dentro do seu projeto no Jitterbit Studio, existem várias maneiras de iniciar uma nova atividade de upsert do NetSuite. Cada uma das opções a seguir iniciará o Assistente de Upsert do NetSuite para guiá-lo pelo processo.

   • Vá para Arquivo > Novo > Conectores > Novo Upsert do NetSuite.
   • Na árvore à esquerda, sob Conectores, clique com o botão direito na categoria NetSuite, e selecione Novo Upsert do NetSuite.
   • Na árvore à esquerda, sob Conectores, clique duas vezes na categoria NetSuite, depois clique com o botão direito em Novo Upsert do NetSuite e selecione Novo Upsert do NetSuite.
   • Na barra de ferramentas superior, clique no ícone do conector (peça de quebra-cabeça laranja) . No popup, selecione NetSuite, depois selecione Upsert do NetSuite.

2. A tela Endpoint do Assistente de Upsert do NetSuite deve abrir na visualização principal do Studio. Esta tela solicita que você selecione o endpoint onde gostaria de criar novos dados ou atualizar dados existentes. Você já deve ter configurado seu endpoint em endpoint do conector NetSuite. Use o menu suspenso para selecionar o endpoint apropriado. Clique em Próximo quando terminar.

   

3. A tela Objeto do Assistente de Upsert do NetSuite solicita que você selecione o objeto onde gostaria de upsertar dados. Neste exemplo, queremos criar um novo registro de cliente e atualizar um registro de cliente existente no NetSuite, então selecionamos o objeto "Cliente" e clicamos em Concluir para continuar.

   Nota

   Se você tiver muitos objetos disponíveis em sua conta do NetSuite, pode ser necessário esperar um momento para que eles carreguem. Você também pode inserir um nome de objeto no campo Filtro ou usar o menu suspenso Objetos a mostrar para limitar os resultados a "Objetos Padrão" ou "Objetos Personalizados". Tente o botão Atualizar se os resultados não forem o que você espera.

1. O Jitterbit irá então prosseguir com a criação de uma estrutura de solicitação e resposta da API do NetSuite que permitirá a inserção e atualização de dados dentro da sua conta conectada do NetSuite. Uma nova aba deve aparecer no Studio chamada NetSuite Upserts. Você pode renomear sua atividade de upsert aqui, se desejar; no exemplo, a nossa é chamada "Exemplo de Upsert de Cliente do NetSuite." Você também pode usar os botões + - ou setas para expandir todos os elementos dentro de cada estrutura.

1. Em seguida, na mesma tela, clique no botão Criar Operação localizado sob Usar em uma Integração no canto superior direito. Isso criará a operação do Jitterbit que irá inserir e atualizar os dados do cliente no NetSuite.

2. Uma nova aba deve abrir no Studio chamada Operações, contendo uma representação gráfica da atividade de upsert.

Salve sua operação clicando no ícone de disco único para salvar apenas esta operação ou no ícone de disco múltiplo para salvar todas as alterações no seu projeto de integração. Você deve ver o asterisco na aba Operações e o título da operação desaparecer à medida que sua nova atividade de upsert é criada e salva no seu projeto.

Definindo os componentes da operação

A seguir, precisamos definir os outros componentes da operação que aparecem na representação gráfica, incluindo Fonte, Solicitação, Resposta e Alvo.

Para cada um, as instruções abaixo orientam você a retornar à representação gráfica da operação que você criou e clicar duas vezes em cada ícone para configurar cada componente. Como alternativa, você também pode criar a Fonte, Solicitação, Resposta e Alvo separadamente e, em seguida, arrastá-los e soltá-los da árvore à esquerda diretamente sobre os ícones na representação visual da sua operação.

Para os propósitos deste guia, fornecemos os seguintes exemplos para referência acima: Jitterpak NetSuiteExample.jpk e arquivos acompanhantes em NetSuiteSampleFiles.zip. Muitos tipos diferentes de dados podem ser usados para cada componente da operação. Para saber mais sobre opções adicionais de personalização, consulte a seção Design Studio de nossa documentação.

• Fonte: No exemplo, usamos um arquivo CSV como a solicitação de entrada para atualizar um cliente existente e criar um novo cliente com os valores de campo fornecidos abaixo. A tabela a seguir exibe o conteúdo do arquivo de exemplo CustomerUpsertRequest.csv.

  ID	Nome	Email	Telefone	Endereço	Cidade	Estado	CEP
  Test Cust 1	Test Customer 1	test1@example.com	1-999-999-9999	1234 Main St.	Denver	CO	80250
  Test Cust 2	Test Customer 2	test2@example.com	1-888-888-8888	1234 Sample Dr.	San Francisco	CA	94101
  Test Cust 3	Test Customer 3	test3@example.com	1-777-777-7777	1234 Example Way	Houston	TX	77001

  Nota

  Um upsert do NetSuite deve incluir um campo ID que mapeie para o ExternalID do cliente no NetSuite. Se houver novos registros que precisam ser criados, usar apenas o InternalID não será suficiente, pois este campo ainda não teria sido criado para novos registros no NetSuite.

  Nota

  Na tabela acima, Test Customer 1 e Test Customer 2 foram originalmente criados no guia NetSuite connector create. O número de telefone do Test Customer 1 foi então atualizado durante o guia NetSuite connector update. O exemplo de um upsert nesta página inclui (1) o número de telefone atualizado do Test Customer 1, então este registro será atualizado se ainda não estiver; caso contrário, permanecerá o mesmo, (2) um número de telefone recém-atualizado para o Test Customer 2, e (3) um novo registro de cliente para adicionar o Test Customer 3.

  Nota

  Uma variedade de tipos de fonte está disponível no Jitterbit. Veja Fontes para mais informações.

  Para usar o arquivo CSV, primeiro clique duas vezes no ícone Fonte, em seguida, clique no botão Criar Nova Fonte e dê um Nome à sua fonte (por exemplo, CustomerUpsertRequest.csv). Em seguida, para este exemplo, estamos usando um agente privado com arquivos locais habilitados, e assim selecione um Tipo de "Arquivo Local" e depois Procurar para a localização. Se você estiver usando os arquivos de exemplo, a Pasta é 'C:\NetSuiteSampleFiles' e o Obter Arquivos é 'CustomerUpsertRequest.csv'. Também expandiremos as Opções e definiremos Ignorar Linhas para Primeiro: '1', uma vez que nosso arquivo CSV usa uma linha de cabeçalho.

• Destino: Clique duas vezes no ícone Destino. No exemplo, registraremos a resposta do NetSuite em um arquivo CSV para fornecer informações sobre sucesso/falha. Clique no botão Criar Novo Destino, dê um Nome ao seu destino (por exemplo, CustomerUpsertResponse.csv) e novamente selecione um Tipo de "Arquivo Local" e Procurar para uma localização no agente privado onde queremos salvar os dados. No exemplo, a Pasta é 'C:\NetSuiteSampleFiles' e o Nome do Arquivo é 'CustomerUpsertResponse.csv'.

  Nota

  Você também pode exportar para uma variedade de diferentes tipos de destino. O tipo não precisa ser o mesmo que o tipo de fonte. Veja Destinos para opções.

• Requisição: Clique duas vezes no ícone Requisição e selecione Criar Nova Transformação. Isso abrirá o Assistente de Transformação, que o guiará na criação da requisição.

  Nota

  Informações adicionais sobre estruturas de requisição estão disponíveis em Transformações.

  1. Na primeira tela, Nome, forneça um Nome para sua transformação ou deixe como o padrão. Em seguida, use o dropdown Fonte para selecionar o tipo de fonte. Para o exemplo, usamos um arquivo CSV, que é considerado "Texto." Clique em Próximo para continuar.

  2. Na próxima tela, Source, use o dropdown Available File Format Definitions para selecionar a mesma definição de formato de arquivo de origem criada durante NetSuite connector create (ou seja, "Exemplo de Arquivo Plano de Cliente").

     Ou, se você estiver criando do zero, pode selecionar Create New. Isso abrirá opções adicionais para definir um novo formato de arquivo. Forneça um Name para o novo formato de arquivo (no exemplo, chamamos o nosso de "Exemplo de Arquivo Plano de Cliente"). Para criar a definição de texto com base em nosso arquivo CSV existente, selecione Create From File, em seguida, na janela pop-up, navegue até o arquivo local 'CustomerUpsertRequest.csv'.

     Clique em Finish para continuar.

  3. A aba Transformations deve abrir onde você pode completar seu mapeamento. Use o + para expandir os itens de origem e destino em cada árvore. Em seguida, arraste e solte cada campo que você gostaria de mapear de uma árvore para a outra.

     Nota

     Um upsert do NetSuite deve incluir um campo ID que mapeia para o ExternalID do cliente no NetSuite. Se houver novos registros que precisam ser criados, usar apenas o InternalID não será suficiente, pois esse campo ainda não teria sido criado para novos registros no NetSuite.

     Seu mapeamento de transformação deve se parecer com o mostrado abaixo:

     

• Response: Clique duas vezes no ícone Response e selecione Create New Transformation. Isso abrirá o Transformation Wizard, que o guiará na criação da resposta.

  Nota

  Informações adicionais sobre estruturas de resposta são fornecidas em Transformations.

  1. Na primeira tela, Name, forneça um Name para sua transformação ou deixe como o padrão. Em seguida, use o dropdown Target para selecionar o tipo de destino. Para o exemplo, usamos um arquivo CSV, que é considerado "Texto." Clique em Next para continuar.

  2. Na próxima tela, Target, use o dropdown Available File Format Definitions para selecionar a mesma definição de formato de arquivo de destino criada durante NetSuite connector create (ou seja, "Estrutura de Resposta do NetSuite").

     Ou, se você estiver criando do zero, pode selecionar Create New. No exemplo, configuramos uma estrutura de resposta típica que gravará o ID externo, status e mensagem na resposta para que recebamos um feedback caso a operação de upsert falhe. Na primeira tela, defina o Name do novo formato de arquivo (no exemplo, o nosso é chamado de "Estrutura de Resposta do NetSuite"), em seguida, clique no botão Create Manually. Na próxima tela, clique em New e adicione três novos campos chamados "ExternalID", "Status" e "Message."

     Clique em Finish para continuar.

  3. A aba Transformations deve abrir onde você pode completar seu mapeamento. Use o + para expandir os lados de origem e destino. Neste exemplo, adicionaremos scripts para obter o ID externo no NetSuite para que, se a operação falhar, agora saibamos o ID do registro que falhou para solucionar problemas. Para fazer isso:

     • Arraste e solte o campo "isSuccess" do lado de origem para o novo campo "Status" do lado de destino.

     • Clique duas vezes no campo "ExternalID" do lado de destino para abrir o Formula Builder e adicione as seguintes funções ao script, em seguida, clique em OK.

       <trans>
       FindByPos(SourceInstanceCount(),jbroot$jbrequest$upsertList$record#.Customer$externalId)
       </trans>
       

       A função FindByPos encontra a instância nos dados solicitados que corresponde à resposta.

     • Clique duas vezes no campo "Message" do lado de destino para abrir o Formula Builder e adicione as seguintes funções ao script, em seguida, clique em OK.

       <trans>
       SumString(jbroot$jbresponse$upsertListResponse$writeResponseList$writeResponse.status$statusDetail#.message$,"|",true)
       </trans>
       

A função SumString irá concatenar um elemento que pode ter mais de uma instância em uma única string.

Seu mapeamento de transformação deve se parecer com o mostrado abaixo:

• Scripts Opcionais: Você pode encontrar funções de script adicionais para usar durante o mapeamento da sua Transformação ou separadamente como Scripts na seção Construtor de Fórmulas. Para informações adicionais, veja Conector do NetSuite avançado.

Implantando e executando a operação

Com a atividade de upsert do NetSuite totalmente configurada, estamos prontos para implantar e executar a operação.

1. Na aba Operações, clique no ícone de implantar .

2. Em seguida, clique no ícone de executar para colocar a operação na fila para execução.

3. Na parte inferior da tela, o Monitor de Operações deve indicar que sua operação foi executada com sucesso. Se não, você pode clicar duas vezes no ícone de Status para visualizar quaisquer mensagens de log.

   

4. Você também deve ver agora a resposta de saída que foi mapeada para seu arquivo de destino. No exemplo, o arquivo agora é criado em 'C:\NetSuiteSampleFiles\CustomerUpsertResponse.csv'. Como a operação foi executada com sucesso, vemos o campo ID seguido por um status de '1', indicando sucesso. Se a operação falhasse, veríamos um '0' junto com uma terceira coluna mostrando a mensagem de erro do log.

   ExternalID	Status	Message
   Test Cust 1	1
   Test Cust 2	1
   Test Cust 3	1

5. Além disso, ao verificar sua conta do NetSuite, você deve encontrar as informações do Test Customer 2 atualizadas com o novo número de telefone, e o registro do Test Customer 3 criado.

   

   Nota

   Você pode encontrar mais informações sobre a chamada da API para o NetSuite no Registro de Uso de Serviços Web disponível no NetSuite em Configuração > Integração > Registro de Uso de Serviços Web. Isso fornece informações detalhadas sobre sucesso/falha, bem como a solicitação e a resposta que foram enviadas para o Jitterbit.