Ir para o conteúdo

Atividade de Upsert em Massa do Salesforce

Introdução

Uma atividade Bulk Upsert do Salesforce atualiza um grande número de registros existentes e insere um grande número de novos registros em um endpoint do Salesforce e destina-se a ser usada como um destino para consumir dados em uma operação. Depois de configurar uma conexão do Salesforce, você pode configurar quantas atividades do Salesforce desejar para cada conexão do Salesforce.

A atividade Bulk Upsert é mais rápida e escalável melhor do que uma atividade Salesforce Upsert não em massa, mas deverá ser usado somente se você não precisar usar uma transformação para alterar os dados antes de atingir seu destino. (As atividades em massa do Salesforce não podem ser usadas com transformações.)

A atividade Bulk Upsert requer o uso de um campo de ID externo para (1) inserir registros se eles ainda não existirem e (2) atualizar registros se eles já existirem. Para obter informações sobre como criar um campo de ID externo no Salesforce, consulte Criar um ID externo do Salesforce para Jitterbit. Se, em vez disso, você quiser inserir em massa apenas novos registros ou se quiser atualizar em massa os registros existentes com base no ID do objeto no Salesforce, use uma atividade de inserção em massa ou atualização em massa do Salesforce.

O conector Salesforce suporta API em massa do Salesforce. Para obter mais informações, consulte Pré-requisitos e versões de API suportadas.

Crie uma Atividade do Salesforce

Uma instância de uma atividade é criada a partir de uma conexão usando um tipo de atividade.

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

Uma atividade existente pode ser editada nestes locais:

Configurar uma Atividade de Upsert em Massa do Salesforce

Siga estas etapas para configurar uma atividade de upload em massa do Salesforce:

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 fazer upload em massa de dados.

atividade de upsert em massa 1 do Salesforce

  • Nome: Insira um nome a ser usado para identificar a atividade do Salesforce Bulk Upsert. O nome deve ser exclusivo para cada atividade de upload em massa 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 fazer upload em massa de dados. Insira qualquer parte do nome do objeto na caixa de pesquisa para filtrar a lista de objetos. A busca não diferencia maiúsculas de minúsculas.

    Nota

    Se o menu suspenso não for preenchido com objetos disponíveis, a Conexão do Salesforce pode não ter sucesso. Certifique-se de estar conectado reabrindo a conexão e testando novamente as credenciais.

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

  • Salvar e Sair: Se ativado, clique para salvar a configuração desta etapa e feche 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 as 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 um ID Externo

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

atividade de upsert em massa 2 do Salesforce

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

    Aviso

    O campo utilizado como ID externo deve ter um valor único para cada registro. Se você tiver vários registros com o mesmo valor de ID externo, uma resposta de erro do Salesforce será retornada e o upsert em massa falhará para os registros com IDs duplicados.

  • 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 as 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: Forneça o Esquema de Resposta

Nesta etapa, carregue ou selecione um arquivo CSV. O arquivo CSV fornecerá o esquema a ser usado na Etapa 4: Cabeçalhos do mapa.

atividade de upsert em massa 3 do Salesforce

  • Fornecer esquema de resposta: O esquema de resposta define o esquema usado pelo arquivo CSV fornecido. Esse esquema de resposta é 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 previamente definido no projeto atual.

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

      • Visualizar esquema: Depois que um esquema existente carregado for selecionado, você poderá 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 carregados existentes e não para flat, hierárquico ou espelhado esquemas personalizados.

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

        • Fornecer novo esquema: Escolha esta opção para definir um novo esquema fazendo upload de um arquivo ou inserindo-o manualmente na área de texto.
      • Nome do esquema: Insira 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 estiver fazendo upload de um arquivo, você pode deixar em branco, pois o nome é preenchido assim que o arquivo é carregado.

      • Carregar arquivo: Clique neste botão para abrir uma caixa de diálogo onde você pode carregar um esquema de um arquivo que pode ser acessado na máquina atual:

        esquema de upload do Salesforce

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

          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 perguntará 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 for utilizado no projeto. Se não quiser substituir o arquivo, clique em Cancelar e modifique manualmente o arquivo para que ele tenha um nome que ainda não esteja sendo usado. Em seguida, tente carregá-lo novamente.

          arquivo de substituição do Salesforce

        • 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 Carregar 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 Carregar arquivo. Outra opção é inserir ou colar manualmente um esquema nesta área sem carregar um esquema de um arquivo.

      • Validação: À medida que você edita um esquema, as informações de validação serão fornecidas abaixo da área de texto, com quaisquer erros relatados uma linha por vez. Ou seja, depois de resolver um erro em uma linha, erros de sintaxe adicionais a serem resolvidos poderão ser relatados nas 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 as 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: Cabeçalhos do Mapa

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

atividade de upsert em massa 4 do Salesforce

  • 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 do arquivo fornecido na etapa anterior.

      • Pesquisar: Insira qualquer parte do nome do cabeçalho na caixa de pesquisa para filtrar a lista de cabeçalhos. A busca 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 informações na caixa de diálogo:

        mapeamentos de importação do Salesforce

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

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

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

          Aviso

          O mapeamento carregado substitui quaisquer mapeamentos existentes, se presentes.

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

      • Exportar mapeamento: Para exportar um mapeamento existente, clique no link Exportar mapeamento. Isso inicia o processo de download em seu navegador. O arquivo exportado está no 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 atividades em massa exportados não podem ser importados como mapeamentos de transformação e pode ser importado somente 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 mapeadas.

      • Pesquisar: Insira qualquer parte do nome da coluna na caixa de pesquisa para filtrar a lista de cabeçalhos. A busca não diferencia maiúsculas de minúsculas.
      • Mapa automático: Clique no link Mapa automático para mapear nomes de campos de origem e de destino que sejam correspondência exata (independentemente do caso) e tenham tipos de dados idênticos. Os campos mapeados automaticamente são adicionais a quaisquer mapeamentos existentes, que são deixados no local.
      • Recomeçar: Clique no link Recomeçar 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 as 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óximos Passos

Depois de configurar uma atividade de Bulk Upsert do Salesforce, você poderá 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.

Conclua a Operação

Depois de configurar uma atividade do Salesforce Bulk Upsert, conclua a configuração da operação adicionando e configurando outras atividades ou scripts como etapas da operação. Você também pode definir as configurações de operação de uma operação, que incluem a capacidade de encadear operações que estejam no mesmo fluxo de trabalho ou em workflows diferentes.

Depois que uma atividade de Bulk Upsert do Salesforce for criada, as ações de menu para essa atividade estarão acessíveis no painel do projeto nas guias Workflows ou Componentes e na quadro de design. Consulte Menu Ações de Atividade para detalhes.

As atividades do Salesforce Bulk Upsert podem ser usadas como destino com este padrão de operação:

Uma atividade do Salesforce pode ser usada como uma etapa de operação em apenas uma operação. Ou seja, não é possível fazer referência à mesma atividade diversas 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).

Outros padrões não são válidos usando atividades de upload em massa do Salesforce. Veja os padrões de validação na página Validade da Operação página.

Um caso de uso típico é usar uma atividade de upload em massa do Salesforce no Padrão de destino em massa do Salesforce. Neste exemplo, a atividade de leitura de FTP (Read Bulk Upsert Request) fornece dados para a operação. A atividade Salesforce Bulk Upsert (Bulk Upsert) é usada como alvo, recebendo dados dentro da operação. Uma mensagem é então registrada pelo script Write to Operation Log:

operação de atividade de upsert em massa do Salesforce 1

Além disso, a origem baseada em arquivo usada na operação deve usar um formato de arquivo simples com um cabeçalho e apenas estes tipos de dados:

Base64 - Boleano - Formatos de data - Dobro - Inteiro - ID do Salesforce - Corda

As operações que usam atividades do Salesforce também podem ter ações 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 e-mail após ocorrer uma falha SOAP. Para obter instruções sobre como disparar uma ação em caso de falha SOAP, consulte Ações de operação.

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

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

Visualizar Arquivos de Sucesso e Falha

Se você estiver executando uma operação contendo uma atividade do Salesforce em um Agente Privado, os arquivos de sucesso e falha estão disponíveis para download na página Atividades do Management Console. Selecione a operação relevante na tabela Atividades e clique na aba Registros de atividades na seção inferior da tela para exibir links de download para os arquivos, se disponíveis:

registros de falha de sucesso

  • Baixar arquivo com sucesso: 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.

  • Falha no download do arquivo: 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.

Nota

Por padrão, os arquivos de sucesso e falha são excluídos automaticamente do Agente Privado após 14 dias pelo Jitterbit File Cleanup Service. O número de dias que os arquivos são salvos pode ser alterado editando o [ResultFiles] seção no jitterbit.conf arquivo. Você também pode alterar as regras de retenção de arquivos de sucesso e falha editando as regras do serviço de limpeza de arquivos Jitterbit para Agentes Privados.

Os downloads do log de atividades estão desativados para Agentes em Nuvem. Se os links estiverem visíveis, você receberá uma mensagem de erro se tentar fazer o download.