Prepare um arquivo CSV para importar ou atualizar no Salesforce

Preparar arquivos CSV

A primeira linha em um arquivo CSV lista os nomes de campo para o objeto que você está processando. Cada linha subsequente corresponde a um registro no Salesforce. Um registro consiste em uma série de campos delimitados por vírgulas. Um arquivo CSV pode conter vários registros e constituir um "lote".

Todos os registros em um arquivo CSV devem ser para o mesmo objeto. Você especifica esse objeto no trabalho associado ao lote. Todos os lotes associados a um trabalho devem conter registros para o mesmo objeto.

Note o seguinte ao processar arquivos CSV com a API em massa:

• A API em massa não tem suporte para nenhum delimitador, exceto por uma vírgula.
• A API em massa é otimizada para processar grandes conjuntos de dados e tem um formato estrito para arquivos CSV (consulte os formatos em Linhas do registro CSV válidas). A maneira mais fácil de processar arquivos CSV é habilitar a API em massa para o Data Loader.
• Você deve incluir todos os campos obrigatórios ao criar um registro. Opcionalmente, você pode incluir qualquer outro campo para o objeto.
• Se você estiver atualizando um registro, quaisquer campos que não estejam definidos no arquivo CSV serão ignorados durante a atualização.
• Os arquivos devem estar no formato UTF-8.

Campos de relacionamento em uma linha do cabeçalho

Muitos objetos no Salesforce estão relacionados a outros objetos. Por exemplo, Conta é um pai de Contato. Você pode adicionar uma referência a um objeto relacionado em um arquivo CSV representando um relacionamento em um cabeçalho de coluna.

Quando você estiver processando registros na API em massa, você usa a sintaxe RelationshipName.IndexedFieldName em um cabeçalho de coluna CSV para descrever o relacionamento entre um objeto e seu pai, em que RelationshipName é o nome do relacionamento do campo e IndexedFieldName é o nome de campo indexado que identifica de maneira única o registro pai. Use a chamada describeSObjects() na API SOAP baseada em SOAP para obter o valor relationshipName para um campo.

Alguns objetos também têm relacionamentos consigo mesmo. Por exemplo, o campo "Reporta-se a" para um contato é uma referência a outro contato. Se você estiver inserindo um contato, poderá usar um cabeçalho de coluna ReportsTo.Email para indicar que está usando um campo de Email de contato para identificar de maneira única o campo Reporta-se a para um contato. A parte ReportsTo do cabeçalho da coluna é o valor da propriedade relationshipName para o campo Reporta-se a. O seguinte arquivo CSV usa um relacionamento:
 

Observação:

• Você pode usar um relacionamento de filho para pai, mas não pode usar um relacionamento de pai para filho.
• Você pode usar um relacionamento de filho para pai, mas não pode estendê-lo para usar um relacionamento de filho para pai.
• Você somente pode usar campos indexados no objeto pai. Um campo personalizado será indexado se o campo ID externo estiver selecionado. Um campo padrão será indexado se sua propriedade idLookup estiver definida como true. Consulte a coluna Propriedades do campo na tabela do campo para cada objeto padrão.

Campos de relacionamento para objetos personalizados

Objetos personalizados usam campos personalizados para rastrear relacionamentos entre objetos. Use o nome do relacionamento, que termina em __r(underscore-underscore-r), para representar um relacionamento entre dois objetos personalizados. Você pode adicionar uma referência a um objeto relacionado representando um relacionamento em um cabeçalho de coluna.

Se o objeto filho tiver um campo personalizado com um Nome de API de Mother_Of_Child__c que aponte para um objeto personalizado pai e o objeto pai tiver um campo com um Nome de API de External_ID__c, use o cabeçalho de coluna Mother_Of_Child__r.External_ID__c para indicar que você está usando o campo de ID externo do objeto pai para identificar de modo exclusivo o campo Mãe do filho. Para usar um nome de relacionamento em um cabeçalho de coluna, substitua __c no campo personalizado do objeto filho por __r.

O seguinte arquivo CSV usa um relacionamento:
 

Relacionamentos para campos polimórficos

Um campo polimórfico pode referir-se a mais de um tipo de objeto como pai. Por exemplo, um contato ou um lead pode ser o pai de uma tarefa. Em outras palavras, o campo WhoId de uma tarefa pode conter o ID de um contato ou de um lead. 

Uma vez que um campo polimórfico é mais flexível, a sintaxe do cabeçalho de coluna tem um elemento extra para definir o tipo do objeto pai. A sintaxe é ObjectType:RelationshipName.IndexedFieldName.

A amostra a seguir inclui dois campos de referência:

1. O campo WhoId é polimórfico e tem um relationshipName de Who. Ele se refere a um lead e o campo Email indexado identifica de maneira exclusiva o registro pai.

2. O campo OwnerId é polimórfico e tem um relationshipName de Owner. Ele se refere a um usuário e o campo ID indexado identifica de maneira exclusiva o registro pai.
 

A parte ObjectType: de um cabeçalho de coluna de campo é necessária somente para um campo polimórfico. Você obtém um erro se omitir essa sintaxe para um campo polimórfico. Você também obtém um erro se incluir essa sintaxe para um campo que não seja polimórfico.
 

Linhas do registro CSV válidas

A API em massa usa um formato estrito para valores de campo para otimizar o processamento para grandes conjuntos de dados. Lembre-se do seguinte ao gerar arquivos CSV que contenham registros do Salesforce:

• O delimitador para valores de campo em uma linha deve ser uma vírgula.
• Se um valor de campo contiver uma vírgula, uma nova linha ou aspas duplas, o valor do campo deverá ficar entre aspas duplas: por exemplo, "Diretor de operações, região do oeste".
• Se um valor de campo contiver aspas duplas, elas deverão ser ignoradas colocando outras aspas duplas antes delas: por exemplo, "Este é o padrão ""ouro""".
• Os valores do campo não são cortados. Um espaço antes ou depois de uma vírgula delimitadora é incluído no valor do campo. Um espaço antes ou depois de aspas duplas gera um erro para a linha. Por exemplo, John,Smith é válido; John, Smith é válido, mas o segundo valor "Smith"; ."John", "Smith" não é válido.
• Valores de campo vazio são ignorados ao atualizar registros. Para definir um valor de campo como nulo, use um valor de campo de #N/A.
• Campos com um tipo de dado duplo podem incluir valores fracionários. Os valores poderão ser armazenados em notação científica se o número for grande o bastante (ou, para números negativos, pequeno o bastante), conforme indicado por Esquema W3C XML Parte 2: Especificação de Datatypes Segunda Edição.

• Como uma solução alternativa, os Usuários podem tentar abrir um arquivo .CSV no Excel e então Salvar. Isso às vezes pode corrigir determinados problemas de formatação.
• Uma única linha inválida pode fazer toda a importação falhar. E pode quebrar o CSV em arquivos menores para ajudar a identificar qual registro e/ou coluna está causando erros ou problemas de importação.

Arquivo CSV de amostra

A seguinte amostra CSV inclui dois registros para o objeto Contato. Cada registro contém seis campos. Você pode incluir qualquer campo para um objeto que você está processando. Se você usar esse arquivo para atualizar contas existentes, quaisquer campos que não estejam definidos no arquivo CSV serão ignorados durante a atualização.

Você deve incluir todos os campos obrigatórios ao criar um registro.
 

Note que o campo Descrição para o último registro inclui uma quebra de linha, assim, o valor do campo fica entre aspas duplas.
 

Considerações ao importar dados para diferentes objetos

• Campos de pesquisa – o ID do Salesforce é uma string alfanumérica de 15 caracteres que diferencia maiúsculas e minúsculas ou de 18 caracteres que não diferencia maiúsculas e minúsculas que identifica um registro específico de modo único. : Para garantir a qualidade dos dados, garanta que todos os IDs do Salesforce que você inserir no Data Loader estejam na caixa correta
• Campos da lista de opções: O valor do seu campo deve corresponder exatamente àquele dos valores na sua lista de opções. Se você fornecer qualquer outro novo valor que não exista na sua lista de opções, ele não será adicionado à sua lista de opções e, em vez disso, levará a uma falha no registro.
• Campos de data: Os campos de dados devem ser formatados em um formato de data específico que o Data Loader aceite, caso contrário, para o Assistente de importação de dados, você não precisa se preocupar em alterar o formato dos campos de data ou hora.
• Campos boolianos: Você pode usar um valor True ou False para mapear. Por exemplo, se você tiver um campo de marca de seleção no seu registro, então para marcar ou desmarcar você pode usar verdadeiro ou falso, respectivamente.
• Campos de moeda: Você não precisa adicionar vírgulas nem sinal monetário. O Salesforce escolherá o formato automaticamente conforme as configurações de moeda padrão da sua organização.
• Endereço de email: Garanta que o email esteja formatado corretamente de acordo com RFC 5321 e não inclua caracteres inválidos que não sejam permitidos conforme protocolos de email internacionais. Alguns exemplos de emails inválidos poderiam ser: 

• Abc.example.com (sem caractere @)
• A@b@c@example.com (somente um @ é permitido fora das aspas)
• a"b(c)d,e:f;g<h>i[j\k]l@example.com (nenhum dos caracteres especiais nesta parte local são permitidos fora das aspas)
• just"not"right@example.com (as strings de aspas devem ser separadas por ponto ou o único elemento compondo a parte local)
• this is"not\allowed@example.com (espaços, aspas e barras invertidas podem existir somente quando dentro de strings com aspas e precedidos por uma barra invertida)
• this\ still\"not\\allowed@example.com (mesmo que ignorado (precedido por uma barra invertida), espaços, aspas e barras invertidas ainda devem estar entre aspas)
• john..doe@example.com (ponto duplo antes do @)
• com advertência: O Gmail deixa isso passar, Email address#Local-part the dots altogether
• john.doe@example..com (ponto duplo após o @)
• um endereço válido com um espaço à esquerda
• um endereço válido com um espaço à direita

• Regra de validação: Garanta que você tenha quaisquer regras de validação aplicadas a qualquer campo e que seu valor esteja de acordo com os critérios para a regra de validação, caso contrário, ocorrerá falha no registro. Outra opção é substituir a regra de validação para desativá-la antes do upload.
• Acionadores: Garanta que você tenha quaisquer acionadores no objeto para o qual você está importando ou atualizando registros, e que seus registros estejam falhando devido a um critério específico não ser atendido. Você pode escolher ignorar o acionador desativando-o antes do upload; depois que o upload for concluído, você poderá reativá-lo.

Ao inserir, excluir ou atualizar arquivos usando o Data Loader do Apex, use a janela Diálogo de mapeamento para associar campos do Salesforce a colunas do seu arquivo CSV.

1. Para combinar automaticamente campos a colunas, clique em Combinar automaticamente campos a colunas. O Data Loader preenche a lista na parte inferior da janela com base na similaridade dos nomes de campo e coluna. Para uma operação de exclusão, a correspondência automática funciona somente no campo ID.

2. Para combinar manualmente campos e colunas, clique e arraste campos da lista dos campos do Salesforce na parte superior da lista dos nomes de cabeçalho da coluna CSV na parte inferior. Por exemplo, se você estiver inserindo novos registros de Conta em que seu arquivo CSV contenha os nomes de novas contas, clique e arraste o campo Nome à direita do campo de cabeçalho da coluna NOME.

3. Opcionalmente, clique em Salvar mapeamento para salvar esse mapeamento para uso futuro. Especifique um nome para o arquivo de mapeamento SDL. Se você selecionar um arquivo existente, o conteúdo do arquivo será substituído. Clique em Sim para confirmar essa ação ou em Não para escolher outro arquivo. 4. Clique em OK para usar seu mapeamento para a operação atual.

Para importar dados de arquivos CSV que não cumprem essas regras, mapeie os campos de dados no arquivo CSV para os campos de dados do Salesforce (consulte Mapear campos de dados para obter mais informações).