Atividade de Upsert em Massa do Salesforce

Introdução

Uma atividade de Upsert em Massa do Salesforce, utilizando 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 um destino para consumir dados em uma operação.

A atividade de Upsert em Massa deve ser utilizada apenas se não for necessário usar uma transformação para alterar dados antes de chegar ao seu destino, uma vez que as atividades em massa do Salesforce não podem ser usadas com transformações. Se for necessário usar uma transformação, utilize a atividade de Upsert do Salesforce.

A atividade de Upsert em Massa 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 de Upsert em Massa é usada para atualizar dados se um registro já existir e criar um se não existir. Se, em vez disso, você deseja apenas inserir novos registros em massa, utilize uma atividade de Inserção em Massa do Salesforce, ou se deseja atualizar registros existentes em massa com base no ID do objeto no Salesforce, utilize uma atividade de Atualização em Massa do Salesforce.

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

Criar uma atividade de Bulk Upsert do Salesforce

Uma instância de uma atividade de Bulk Upsert do Salesforce é criada a partir de uma conexão do 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 mais detalhes, veja Criar uma instância de atividade ou ferramenta em Reutilização de componentes.

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

• A tela de design (veja Menu de ações do componente em Tela de design).

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

Configurar uma atividade de Bulk Upsert do Salesforce

Siga estas etapas para configurar uma atividade de 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 o bulk upsert de dados.

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

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

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

Passo 1: Insira um nome e selecione um objeto

Neste passo, você fornece um nome para a atividade e seleciona um objeto a ser usado ao realizar a inserção em massa de dados.

• Nome: Insira um nome para identificar a atividade de Inserção em Massa do Salesforce. O nome deve ser exclusivo para cada atividade de Inserção 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 realizar a inserção em massa de dados. 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, observe as seguintes dicas de solução de problemas:

  • A conexão do Salesforce pode não ter sido bem-sucedida. Certifique-se de que você está conectado reabrindo a conexão e testando novamente as credenciais.

  • Uma senha do Salesforce que utiliza caracteres ASCII estendidos, como £, pode causar o seguinte erro ao buscar dados durante a configuração da atividade:

    Nome de usuário, senha, token de segurança inválidos; ou usuário bloqueado. [INVALID_LOGIN]
    

    Nesse caso, o teste de conexão pode ainda ser bem-sucedido. Se você receber esse erro durante a configuração da atividade e estiver usando caracteres especiais na senha, tente alterar a senha.

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

• Salvar e Sair: Se habilitado, clique para salvar a configuração deste passo e fechar a configuração da atividade.

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

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

Etapa 2: Especificar um ID externo

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

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

  Warning

  O campo usado 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 alterações, clique para fechar a configuração sem salvar as alterações feitas em qualquer etapa. Uma mensagem pede para você confirmar que deseja descartar as alterações.

Etapa 3: Fornecer o esquema da solicitação

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

• Fornecer esquema de solicitação: Um arquivo CSV carregado ou existente define o esquema que é utilizado 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

  Esquemas para atividades em massa do Salesforce são sempre parte da atividade e nunca podem ser definidos em uma transformação, pois transformações não podem ser usadas em uma operação que possui 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: Após selecionar um esquema carregado existente, 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 exibição de esquemas carregados existentes e não para esquemas personalizados plano, hierárquico ou espelhado.

    • 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 carregando um arquivo ou inserindo manualmente um 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 é tratado como CSV por padrão. Se você estiver carregando um arquivo, pode deixar isso 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 seja acessível a partir da máquina atual:

      • Arquivo: Use o botão Procurar para buscar um arquivo plano com um cabeçalho que ainda não foi utilizado no projeto atual. Arquivos de até 5 MB podem ser enviados.

        Aviso

        Se você tentar enviar 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 lugares onde é utilizado no projeto. Se você não quiser substituir o arquivo, clique em Cancelar e, em seguida, modifique manualmente o arquivo para que tenha um nome que não esteja sendo utilizado, e tente enviá-lo 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 Enviar Arquivo de Esquema sem salvar.

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

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

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

• Próximo: Clique para armazenar temporariamente a configuração para esta 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 qualquer etapa. Uma mensagem pede para você confirmar 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 de solicitação para os campos desejados do Salesforce dos registros que serão 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 completar um mapeamento, arraste um campo de origem à esquerda para um campo de destino à direita. Quando os campos estão mapeados, o fundo fica laranja e uma linha é desenhada entre os campos mapeados. Para remover um mapeamento, clique em qualquer um dos campos de origem ou de destino.

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

    • Pesquisar: Insira 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 então forneça 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 (a partir da opção do Design Studio para Salvar Mapeamentos em Arquivo descrita em Mapeamento de transformação no assistente de processo em massa do Salesforce para ação de inserção).

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

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

      • Carregar: Após selecionar um arquivo, clique em Carregar para enviar o mapeamento.

        Warning

        O mapeamento enviado sobrescreve quaisquer mapeamentos existentes, se houver.

      • Cancelar: Clique em Cancelar para fechar a caixa de diálogo de importação sem enviar 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á 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.

      Note

      Mapeamentos de atividades 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 mapeadas.

    • Pesquisar: Insira 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.

    • Automapear: Clique no link Automapear para mapear nomes de campos de origem e destino que são correspondências exatas (independentemente de maiúsculas e minúsculas) e têm tipos de dados idênticos. Campos que são automapeados são adicionais a quaisquer mapeamentos existentes, que permanecem inalterados.

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

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

• Concluído: Clique para salvar a configuração para 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 qualquer etapa. Uma mensagem pede para você confirmar que deseja descartar as alterações.

Próximas etapas

Após configurar uma atividade de Bulk Upsert do Salesforce, você pode usá-la dentro de uma operação conforme descrito abaixo. Após 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.

Complete a operação

Após configurar uma atividade Bulk Upsert do Salesforce, complete 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 ou em diferentes fluxos de trabalho.

As ações do menu para uma atividade estão acessíveis a partir do painel do projeto e da tela de design. Para mais detalhes, veja o menu de ações da atividade em Conceitos básicos do conector.

Atividades Bulk Upsert do Salesforce podem ser usadas como um alvo com o padrão de alvo em massa do Salesforce. Outros padrões não são válidos usando atividades Bulk Upsert do Salesforce. Veja os padrões de validação na página de 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 outras atividades, exceto aquelas associadas aos conectores de 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 uma etapa de operação em apenas uma única operação. Ou seja, você não pode referenciar a mesma atividade várias vezes dentro de outras operações. Em vez disso, você pode fazer uma cópia de uma atividade do Salesforce para usar em outro lugar (veja Reutilização de componentes).

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

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

Operações que utilizam atividades do Salesforce também podem ter ações de operação configuradas para serem acionadas em um erro 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 a ocorrência de um erro SOAP. Para instruções sobre como acionar uma ação em um erro 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, em seguida, 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

Arquivos de sucesso e falha para a 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 em nuvem quanto 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 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, os arquivos de sucesso e falha estão disponíveis para download na página Operações em Tempo de Execução do Console de Gerenciamento. Selecione a operação relevante na tabela Operações em Tempo de Execução e clique na guia Logs de Atividade na seção inferior da tela para exibir os links de download para os arquivos, se disponíveis:

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

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