Atividade Salesforce Bulk Upsert no Jitterbit Studio

Introdução

Uma atividade Bulk Upsert do Salesforce, usando sua conexão Salesforce, atualiza um grande número de registros existentes e insere um grande número de novos registros no Salesforce, sendo destinada a ser usada como destino para consumir dados em uma operação.

A atividade Bulk Upsert deve ser usada apenas se não for necessário usar uma transformação para alterar dados antes de chegar ao destino, pois as atividades em massa do Salesforce não podem ser usadas com transformações. Se precisar usar uma transformação, use a atividade Upsert do Salesforce.

A atividade Bulk Upsert requer o uso de um campo de ID externo. Para informações sobre como criar um campo de ID externo no Salesforce, consulte Criar um ID externo do Salesforce para Jitterbit.

A atividade Bulk Upsert é usada para atualizar dados se um registro já existe e criar um se não existir. Se preferir apenas inserir em massa novos registros, use uma atividade Bulk Insert do Salesforce, ou se quiser atualizar em massa registros existentes com base no ID do objeto no Salesforce, use uma atividade Bulk Update do Salesforce.

As atividades em massa do Salesforce usam a Salesforce Bulk API baseada em SOAP. Para mais informações, consulte Pré-requisitos e versões de API suportadas.

Criar uma atividade Salesforce Bulk Upsert

Uma instância de uma atividade Bulk Upsert do Salesforce é criada a partir de uma conexão Salesforce usando seu tipo de atividade Bulk Upsert.

Para criar uma instância de uma atividade, arraste o tipo de atividade para a tela de design ou copie o tipo de atividade e cole-o na tela de design. Para detalhes, consulte Criar uma instância de atividade ou ferramenta em Reutilização de componentes.

Uma atividade Bulk Upsert do Salesforce existente pode ser editada a partir destes locais:

• A tela de design (consulte Menu de ações de componentes em Tela de design).

• A aba Componentes do painel de projeto (consulte Menu de ações de componentes em Aba Componentes do painel de projeto).

Configurar uma atividade Salesforce Bulk Upsert

Siga estas etapas para configurar uma atividade Bulk Upsert do Salesforce:

• Etapa 1: Insira um nome e selecione um objeto
  Forneça um nome para a atividade e selecione um objeto a ser usado ao fazer upsert em massa de dados.

• Etapa 2: Especifique um ID externo
  Selecione um campo Salesforce existente que deseja que o Harmony use como ID externo para associar registros.

• Etapa 3: Forneça o esquema de solicitação
  Carregue ou selecione um arquivo CSV. Isso fornecerá o esquema a ser usado na etapa final.

• Etapa 4: Mapear cabeçalhos
  Mapeie os cabeçalhos do arquivo de origem fornecidos pelo arquivo CSV com os campos Salesforce desejados dos registros a serem inseridos em massa.

Etapa 1: Insira um nome e selecione um objeto

Nesta etapa, você fornece um nome para a atividade e seleciona um objeto a ser usado ao inserir dados em massa.

• Menu de endpoint: Se você tiver vários endpoints do mesmo tipo de conector configurados, um menu na parte superior da tela exibe o nome do endpoint atual. Clique no menu para alternar para um endpoint diferente. Para mais informações, consulte Alterar o endpoint atribuído em Telas de configuração.

  • Editar endpoint: Aparece ao passar o mouse sobre o nome do endpoint atual. Clique para editar a configuração de conexão do endpoint selecionado.

• Nome: Insira um nome para identificar a atividade Bulk Upsert do Salesforce. O nome deve ser único para cada atividade Bulk Upsert do Salesforce e não deve conter barras (/) ou dois-pontos (:).

• Selecione a referência do objeto: Use o menu suspenso para selecionar um objeto padrão ou personalizado do Salesforce para inserir dados em massa. Insira o valor de qualquer coluna na caixa de pesquisa para filtrar a lista de objetos. A pesquisa não diferencia maiúsculas de minúsculas.

  Nota

  Se a lista não for preenchida com objetos disponíveis, a conexão Salesforce pode não ter sido bem-sucedida. Certifique-se de estar conectado reabrindo a conexão e testando novamente as credenciais.

• Configurações opcionais: Clique para expandir uma configuração opcional adicional.

  • Modo de concorrência: Selecione o modo de concorrência para o carregamento de dados em massa, Paralelo (padrão) ou Serial. Para mais informações sobre ressalvas e quando usar o modo serial, consulte as Diretrizes gerais do Salesforce para carregamentos de dados.

• Atualizar: Clique no ícone de atualização para recarregar objetos do endpoint Salesforce. Isso pode ser útil se você adicionou objetos ao Salesforce recentemente.

• Salvar e sair: Se habilitado, clique para salvar a configuração desta etapa e fechar a configuração da atividade.

• Próximo: Clique para armazenar temporariamente a configuração desta etapa e continuar para a próxima etapa. A configuração não será salva até que você clique no botão Concluído na última etapa.

• Descartar alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em nenhuma etapa. Uma mensagem solicita que você confirme que deseja descartar as alterações.

Etapa 2: Especifique uma ID externa

Nesta etapa, você seleciona um campo Salesforce existente que deseja que o Harmony use como a ID externa para associar registros.

• ID externa: Use o menu suspenso para selecionar o campo Salesforce existente que você deseja que o Harmony use como a ID externa para associar registros. Para informações sobre como criar um campo de ID externa no Salesforce, consulte Criar uma ID externa do Salesforce para Jitterbit.

  Aviso

  O campo usado como ID externa deve ter um valor único para cada registro. Se você tiver vários registros com o mesmo valor de ID externa, uma resposta de erro do Salesforce será retornada e a inserção em massa falhará para os registros com IDs duplicadas.

• Voltar: Clique para armazenar temporariamente a configuração desta etapa e retornar à etapa anterior.

• Próximo: Clique para armazenar temporariamente a configuração desta etapa e continuar para a próxima etapa. A configuração não será salva até que você clique no botão Concluído na última etapa.

• Descartar alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em nenhuma etapa. Uma mensagem solicita que você confirme que deseja descartar as alterações.

Etapa 3: Fornecer o esquema da solicitação

Nesta etapa, faça upload ou selecione um arquivo CSV. O arquivo CSV fornecerá o esquema a ser usado na Etapa 4: Mapear cabeçalhos.

• Fornecer esquema da solicitação: Um arquivo CSV enviado ou existente define o esquema usado na solicitação. Este esquema é usado como parte da atividade em massa do Salesforce para criar mapeamentos na próxima etapa. Selecione uma das duas opções abaixo.

  Nota

  Os esquemas para atividades em massa do Salesforce sempre fazem parte da atividade e nunca podem ser definidos em uma transformação, pois as transformações não podem ser usadas em uma operação que tenha uma atividade em massa do Salesforce.

  • Usar esquema salvo: Escolha esta opção para selecionar um esquema existente que foi definido anteriormente no projeto atual.

    • Esquemas salvos: Use o menu suspenso para selecionar um esquema existente para reutilizar.

    • Visualizar esquema: Depois que um esquema existente enviado é selecionado, você pode visualizar o esquema diretamente na área de texto abaixo do menu suspenso. Embora um esquema salvo não seja editável, esta área de texto pode ser copiada usando Control+C (Windows ou Linux) ou Command+C (macOS). Esta área de texto é apenas para a exibição de esquemas enviados existentes e não para esquemas simples, hierárquicos ou espelhados personalizados.

    • Validação: As informações de validação são fornecidas abaixo da área de texto e baseiam-se na extensão de arquivo do esquema salvo.

  • Fornecer novo esquema: Escolha esta opção para definir um novo esquema fazendo upload de um arquivo ou inserindo um manualmente na área de texto.

    • Nome do esquema: Digite um nome para o esquema na caixa de texto superior, incluindo a extensão do arquivo. Se nenhuma extensão de arquivo for fornecida, o arquivo será tratado como CSV por padrão. Se você estiver fazendo upload de um arquivo, pode deixar em branco, pois o nome é preenchido após o carregamento do arquivo.

    • Upload de arquivo: Clique neste botão para abrir uma caixa de diálogo onde você pode carregar um esquema de um arquivo acessível a partir da máquina atual:

      • Arquivo: Use o botão Procurar para procurar um arquivo simples com um cabeçalho que ainda não tenha sido usado no projeto atual. Arquivos de até 5 MB podem ser enviados.

        Aviso

        Se você tentar fazer upload de um arquivo com o mesmo nome de um arquivo existente já definido no projeto, uma caixa de diálogo pergunta se você deseja substituir o arquivo existente. Se você clicar em Continuar, o arquivo será substituído pelo novo arquivo com o mesmo nome em todos os locais onde é usado no projeto. Se não quiser substituir o arquivo, clique em Cancelar e modifique manualmente o arquivo para que tenha um nome que ainda não esteja sendo usado, depois tente fazer upload novamente.

      • Carregar: Clique neste botão para carregar o esquema do arquivo. Observe que alguns dados podem ser convertidos durante o processamento conforme descrito em Processamento de esquema.

      • Cancelar: Clique em Cancelar para fechar a caixa de diálogo Upload de arquivo de esquema sem salvar.

    • Visualizar/editar esquema: Depois que um esquema é carregado, você pode visualizá-lo ou editá-lo diretamente na área de texto abaixo do botão Upload de arquivo. Outra opção é inserir ou colar manualmente um esquema nesta área sem carregar um esquema de um arquivo.

    • Validação: Conforme você edita um esquema, as informações de validação serão fornecidas abaixo da área de texto, com erros relatados uma linha por vez. Ou seja, após resolver um erro em uma linha, erros de sintaxe adicionais a resolver podem ser relatados para linhas subsequentes. A validação é baseada na extensão de arquivo do esquema fornecido.

• Voltar: Clique para armazenar temporariamente a configuração desta etapa e retornar à etapa anterior.

• Próximo: Clique para armazenar temporariamente a configuração desta etapa e continuar para a próxima etapa. A configuração não será salva até que você clique no botão Concluído na última etapa.

• Descartar alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em nenhuma etapa. Uma mensagem solicita que você confirme que deseja descartar as alterações.

Etapa 4: Mapear cabeçalhos

Nesta etapa, você mapeia os cabeçalhos do arquivo de origem do arquivo CSV fornecido na Etapa 3: Fornecer o esquema da solicitação para os campos Salesforce desejados dos registros a serem inseridos em massa.

• Mapear Cabeçalhos: Esta etapa é usada para mapear campos por coluna no arquivo de origem para aqueles na atividade de destino em massa do Salesforce. Para concluir um mapeamento, arraste um campo de origem à esquerda para um campo de destino à direita. Quando os campos são mapeados, o fundo fica laranja e uma linha é desenhada entre os campos mapeados. Para remover um mapeamento, clique no campo de origem ou no campo de destino.

  • Cabeçalhos do arquivo de origem: O lado esquerdo mostra os cabeçalhos das colunas no arquivo fornecido na etapa anterior.

    • Pesquisar: Digite o valor de qualquer coluna na caixa de pesquisa para filtrar a lista de cabeçalhos. A pesquisa não diferencia maiúsculas de minúsculas.

    • Importar Mapeamento: Para importar um mapeamento que foi exportado anteriormente, clique no link Importar Mapeamento e forneça entrada na caixa de diálogo que aparecerá:

      • Tipo de Arquivo: Use o menu suspenso para selecionar o formato do arquivo de mapeamento:

        • JDL: Selecione JDL para usar um arquivo que foi exportado de uma operação de processo em massa do Design Studio (da opção Design Studio Salvar Mapeamentos em Arquivo descrita em Mapeamento de transformação em Assistente de processo em massa do Salesforce para ação de inserção).

        • JSON: Selecione JSON para usar um arquivo que foi exportado do Studio usando o link Exportar Mapeamento descrito abaixo.

      • Arquivo: Clique no botão Procurar à direita para selecionar um arquivo que contém o mapeamento.

      • Enviar: Após selecionar um arquivo, clique em Enviar para fazer upload do mapeamento.

        Aviso

        O mapeamento enviado sobrescreve qualquer mapeamento existente, se presente.

      • Cancelar: Clique em Cancelar para fechar a caixa de diálogo de importação sem fazer upload de um mapeamento.

    • Exportar Mapeamento: Para exportar um mapeamento existente, clique no link Exportar Mapeamento. Isso inicia o processo de download no seu navegador. O arquivo exportado está em formato JSON. Cada mapeamento de campo inclui o nome do campo de origem, o nome do campo de destino e o índice de origem.

      Nota

      Os mapeamentos de atividade em massa exportados não podem ser importados como mapeamentos de transformação e podem ser importados apenas usando o link Importar Mapeamento descrito acima.

  • Campos do Salesforce: O lado direito mostra os nomes das colunas no Salesforce que estão disponíveis para serem mapeados.

    • Pesquisar: Digite o valor de qualquer coluna na caixa de pesquisa para filtrar a lista de cabeçalhos. A pesquisa não diferencia maiúsculas de minúsculas.

    • Mapeamento Automático: Clique no link Mapeamento Automático para mapear nomes de campos de origem e destino que correspondem exatamente (independentemente de maiúsculas/minúsculas) e têm tipos de dados idênticos. Os campos mapeados automaticamente são adicionados a qualquer mapeamento existente, que permanece em vigor.

    • Começar Novamente: Clique no link Começar Novamente para limpar todos os mapeamentos.

• Voltar: Clique para armazenar temporariamente a configuração desta etapa e retornar à etapa anterior.

• Concluído: Clique para salvar a configuração de todas as etapas e fechar a configuração da atividade.

• Descartar alterações: Após fazer alterações, clique para fechar a configuração sem salvar as alterações feitas em nenhuma etapa. Uma mensagem solicita que você confirme que deseja descartar as alterações.

Próximas etapas

Após configurar uma atividade Bulk Upsert do Salesforce, você pode usá-la em uma operação conforme descrito abaixo. Depois de executar uma operação contendo uma atividade do Salesforce em um agente privado, você pode baixar os arquivos de sucesso e falha da operação.

Concluir a operação

Após configurar uma atividade Bulk Upsert do Salesforce, conclua a configuração da operação adicionando e configurando outras atividades ou ferramentas como etapas da operação. Você também pode configurar as definições da operação, que incluem a capacidade de encadear operações que estão no mesmo fluxo de trabalho ou em fluxos diferentes.

As ações de menu de uma atividade são acessíveis no painel do projeto e na tela de design. Para obter detalhes, consulte Menu de ações de atividade em Noções básicas do conector.

As atividades Bulk Upsert do Salesforce podem ser usadas como destino com o padrão de destino em massa do Salesforce. Outros padrões não são válidos ao usar atividades Bulk Upsert do Salesforce. Consulte os padrões de validação na página Validade da operação.

Operações que contêm uma atividade do Salesforce podem ter apenas uma atividade do Salesforce e não podem conter nenhuma outra atividade, exceto aquelas associadas aos conectores API, Banco de dados, Compartilhamento de arquivos, FTP, HTTP, Armazenamento local, Armazenamento temporário ou Variável.

Uma atividade do Salesforce pode ser usada como etapa de operação em apenas uma única operação. Ou seja, você não pode referenciar a mesma atividade várias vezes em outras operações. Em vez disso, você pode fazer uma cópia de uma atividade do Salesforce para usar em outro lugar (consulte Reutilização de componentes).

Além disso, o destino baseado em arquivo usado na operação deve estar usando um formato de arquivo simples com um cabeçalho e apenas os seguintes tipos de dados:

• Base64
• Booleano
• Formatos de data
• Double
• Integer
• ID do Salesforce
• String

Operações que usam atividades do Salesforce também podem ter ações de operação configuradas para serem acionadas em uma falha SOAP — um erro resultante de um formato de mensagem incorreto, processamento de cabeçalho ou incompatibilidade. As ações de operação podem ser configuradas para executar uma operação ou enviar um email após uma falha SOAP. Para obter instruções sobre como acionar uma ação em caso de falha SOAP, consulte Ações de operação.

Para usar a atividade com funções de script, escreva os dados em um local temporário e depois use esse local temporário na função de script.

Quando estiver pronto, implante e execute a operação e valide o comportamento verificando os logs da operação.

Arquivos de sucesso e falha

Os arquivos de sucesso e falha da atividade Bulk Upsert podem ser enviados para um endpoint baseado em arquivo, enviados por email ou baixados, dependendo do tipo de agente.

Usando opções de operação em massa

Ao usar um tipo de atividade em massa, tanto agentes na nuvem quanto agentes privados podem usar as opções de operação em massa do Salesforce para enviar arquivos de sucesso e falha para um endpoint baseado em arquivo ou uma notificação por email configurada. Para obter informações detalhadas, consulte Opções de operação em massa do Salesforce em Opções de operação.

Baixando arquivos (apenas agentes privados)

Se você estiver executando uma operação contendo uma atividade do Salesforce em um agente privado, arquivos de sucesso e falha estão disponíveis para download na página Runtime do Console de Gerenciamento. Selecione a operação relevante na tabela Runtime e clique na aba Activity Logs na seção inferior da tela para exibir links de download dos arquivos, se disponíveis:

• Download Success File: Se você estiver executando a operação em um agente privado, clique no link Download para salvar os registros de sucesso como um arquivo CSV.

• Download Failure File: Se você estiver executando a operação em um agente privado, clique no link Download para salvar os registros de falha como um arquivo CSV.