> For the complete documentation index, see [llms.txt](https://docs.flosum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flosum.com/data-migrator/data-migrator-pt-br/modelos/migracao/como-o-mapeamento-de-registros-funciona.md).

# Como o mapeamento de registros funciona

## ![](https://3756291079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvaxzColPOlNbsq4imqpd%2Fuploads%2FcfMTqg4Brbm9baWutclZ%2FSummary2-Small-Icon.svg?alt=media\&token=d1cf162d-c02d-4184-988e-7f7350e450fc) Visão geral

O Data Migrator usa o mapeamento de registros para manter os registros precisos em várias execuções de migração. Quando você habilita o mapeamento de registros para um objeto, o Data Migrator mapeia registros individuais entre as organizações de origem e destino para que as migrações subsequentes adicionem apenas novos registros e atualizem os existentes. Você controla o mapeamento de registros individualmente para cada objeto em um template. O Data Migrator oferece dois métodos para mapear registros entre as organizações de origem e destino: **Automático** e **Manual**. As seções a seguir descrevem como cada método funciona e incluem cenários de exemplo que ilustram o mapeamento de registros bem-sucedido e com falha.

* [#automatic-record-mapping](#automatic-record-mapping "mention")
* [#manual-record-mapping](#manual-record-mapping "mention")
* [#record-mapping-scenarios](#record-mapping-scenarios "mention")

{% hint style="info" %}

#### Habilitando o mapeamento de registros

Por padrão, o mapeamento de registros está desabilitado para todos os objetos em um template. Sem o mapeamento de registros habilitado, todos os registros de origem são sempre inseridos na organização de destino durante a migração. Isso pode resultar em duplicatas se o mesmo registro existir em ambos os locais.

O mapeamento de registros de um objeto é habilitado na guia Configurações dele. O artigo a seguir descreve como habilitar o mapeamento de registros para um objeto.

* [Definindo o mapeamento de registros do objeto](/data-migrator/data-migrator-pt-br/modelos/designer-de-modelos/definindo-o-mapeamento-de-registros-do-objeto.md)
  {% endhint %}

## Mapeamento automático de registros

O mapeamento automático de registros é uma estratégia com estado, baseada em mapeamento, que usa uma tabela interna de mapeamento para vincular registros de origem e destino. Ele depende de mapeamentos históricos de implantações anteriores, em vez de dados de destino em tempo real. Depois que existe um mapeamento de origem para destino, a relação fica fixa, então não há ambiguidade para registros já migrados usando o Automático.

O Automático foi projetado para migrações repetidas quando:

* O Data Migrator é a única ferramenta de migração em uso
* A org de destino está vazia durante a primeira migração
* É necessária consistência de longo prazo entre execuções

O Automático garante que:

* O mesmo registro de origem sempre atualiza o mesmo registro de destino mapeado
* Alterações nos campos de negócio não afetam a correspondência de registros
* As atualizações de registros são determinísticas depois que um mapeamento existe

No entanto, o Automático não avalia dados de destino em tempo real.

### Como o Automático funciona

O Automático segue um processo determinístico, orientado por mapeamento. O diagrama abaixo ilustra o fluxo completo.

<figure><img src="https://3756291079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvaxzColPOlNbsq4imqpd%2Fuploads%2FHQ3R5paTJEYcCDt5ZNZi%2FFlosum%20Data%20Migrator%20VEID%20Flow.png?alt=media&amp;token=e9ff49d1-056a-490d-940a-b979f06cfd64" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

#### Ler registro de origem

Cada registro de origem é processado individualmente durante a execução da migração.
{% endstep %}

{% step %}

#### Localizar mapeamento no banco de dados

O sistema verifica se já existe um mapeamento para o ID do registro de origem.
{% endstep %}

{% step %}

#### Avaliar o resultado do mapeamento

<table><thead><tr><th width="180.33331298828125">Mapeamento encontrado</th><th>Ação</th></tr></thead><tbody><tr><td>Não</td><td>INSIRA um novo registro na org de destino.</td></tr><tr><td>Sim</td><td>ATUALIZE o registro de destino mapeado existente.</td></tr></tbody></table>
{% endstep %}

{% step %}

#### Salvar o mapeamento

Quando nenhum mapeamento existe, o sistema insere o registro na org de destino e cria um novo mapeamento. Nas migrações subsequentes, esse registro é atualizado em vez de ser inserido novamente. Esse processo se repete a cada execução, então os novos registros de origem adicionados são acompanhados no banco de dados.
{% endstep %}
{% endstepper %}

### Limitações

{% hint style="warning" %}

#### Limitações Importantes do Mapeamento Automático de Registros

* O Automático não pode mapear registros que já existem na organização de destino.
* Se outra ferramenta ou processo manual criar ou modificar registros na organização de destino, os mapeamentos Automáticos podem ficar desatualizados, levando a registros duplicados.
* O Automático só pode rastrear registros migrados por meio do Data Migrator.
  {% endhint %}

#### Mapeamento desatualizado

O Automático é tão confiável quanto seu banco de dados. Os mapeamentos ficam desatualizados quando registros são criados na org de destino, seja manualmente ou por meio de outra ferramenta. O exemplo abaixo mostra como isso leva a registros duplicados.

**Exemplo:**

1. Um usuário executa uma migração de todos os registros de Contato para uma org vazia.
   1. Todos os registros de Contato são copiados da org de origem para a org de destino.
   2. Mapeamentos automáticos são criados para cada registro.
2. O usuário cria manualmente registros de Contato para **Charlie** e **Alice** nas orgs de origem e de destino.
3. O usuário executa outra migração de todos os registros de Contato da org de origem para a org de destino.
   1. **Charlie** e **Alice** não têm mapeamento automático porque não foram migrados antes.
   2. Novos registros para **Charlie** e **Alice** são criados na org de destino.
   3. A org de destino agora tem registros duplicados para **Charlie** e **Alice**: um da criação manual e outro da migração.

## Mapeamento manual de registros

O mapeamento manual de registros combina um ou mais campos de registro em um ID composto que vincula registros de origem e destino. Ao contrário dos IDs externos padrão do Salesforce, qualquer campo pode ser usado no ID composto. Quando o Manual pesquisa a org de destino e encontra exatamente um registro correspondente, ele atualiza esse registro em vez de inserir um novo.

Ele foi projetado para migrar registros para orgs de destino que já contêm registros não mapeados anteriormente com o mapeamento automático de registros, ou para registros na org de destino criados por outras ferramentas. Escolha os campos do mapeamento manual com cuidado: se o valor de qualquer campo selecionado mudar, o mapeamento não corresponderá mais ao registro migrado anteriormente.

### Como o Manual funciona

Antes de usar o mapeamento manual de registros para migrar registros, você deve selecionar um ou mais campos para o objeto a serem usados no mapeamento de registros. Os campos selecionados são combinados para criar uma chave que é ao mesmo tempo exclusiva e estável. Isso significa que a chave não muda quando campos de registro comumente atualizados mudam, e ela é exclusiva para cada registro na org. Você pode escolher um ou mais campos para usar na chave Manual. Quanto mais campos você selecionar, maior a probabilidade de a chave ser exclusiva. No entanto, selecionar mais campos também aumenta a chance de a chave ser instável.

Durante o mapeamento manual de registros, o processo pesquisa na org de destino correspondências com a chave gerada. O diagrama e a explicação abaixo ilustram como isso funciona.

<figure><img src="https://3756291079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvaxzColPOlNbsq4imqpd%2Fuploads%2FSS7vNmCOIbsfbeAEDUTo%2FFlosum%20Data%20Migrator%20CEID%20Flow.png?alt=media&amp;token=2b82cea9-8699-4038-a8ad-e88ed6380754" alt=""><figcaption></figcaption></figure>

{% stepper %}
{% step %}

### Ler registro de origem

Cada registro de origem é processado individualmente durante a execução da migração.
{% endstep %}

{% step %}

### Gerar chave

Um **CHAVE** é gerada a partir dos campos do registro selecionados para o mapeamento Manual.
{% endstep %}

{% step %}

### Consultar a org de destino

Execute uma consulta SOQL na org de destino para a **CHAVE**.
{% endstep %}

{% step %}

### Avaliar o resultado da consulta

<table><thead><tr><th width="219.6666259765625">Número de registros correspondentes</th><th>Ação</th></tr></thead><tbody><tr><td>0</td><td>INSIRA um novo registro na org de destino.</td></tr><tr><td>1</td><td>ATUALIZE o registro de destino correspondente existente.</td></tr><tr><td>2 ou mais</td><td>ERRO - o registro é ignorado. Mais de um registro corresponde à <strong>CHAVE</strong>, portanto a chave Manual para este registro não é exclusiva e o registro não pode ser migrado.</td></tr></tbody></table>
{% endstep %}
{% endstepper %}

### Limitações

{% hint style="warning" %}

#### Limitações Importantes do Mapeamento Manual de Registros

Selecionar uma combinação de campos estáveis que criem um ID único para cada registro é fundamental.

* **Estável**: Se um valor em um dos campos selecionados para a chave mudar, o mapeamento Manual não corresponderá mais ao registro migrado anteriormente, e um novo registro será inserido, resultando em uma duplicata.
* **Único**: Se dois ou mais registros compartilharem a mesma chave na organização de origem, a migração não poderá mapeá-los corretamente para os registros de destino porque a chave não é única.
  {% endhint %}

#### Campos manuais inadequados

O mapeamento manual de registros só é confiável se os campos escolhidos para o mapeamento Manual criarem uma chave que seja ao mesmo tempo estável e exclusiva. Abaixo estão exemplos de escolhas ruins de campos.

Os exemplos a seguir usam o objeto Contato.

<table><thead><tr><th width="220">Campos selecionados para a chave</th><th>Por que esses campos são uma má escolha</th></tr></thead><tbody><tr><td><code>Nome</code> e <code>Cidade</code></td><td>Embora <code>Nome</code> mude raramente, combiná-lo com <code>Cidade</code> torna a chave instável, porque a cidade de um contato pode mudar.</td></tr><tr><td><code>Cargo</code> e <code>Departamento</code></td><td>Essa combinação não é exclusiva: vários contatos podem ter o mesmo cargo e departamento.</td></tr><tr><td><code>Nome</code> e <code>Data de nascimento</code></td><td>Essa combinação parece exclusiva e estável, mas <code>Data de nascimento</code> geralmente fica em branco no início e é preenchida depois, o que torna a chave instável.</td></tr></tbody></table>

## Cenários de mapeamento de registros

{% hint style="success" %}

#### Design do template

Objeto: **Contato**

* Campo: **Nome**
* Campo: **E-mail**
* Campo: **Cidade**
  {% endhint %}

As tabelas abaixo mostram os registros de origem e destino, com as diferenças em negrito.

**Registros de Contato da org de origem**

<table><thead><tr><th width="200.3333740234375">ID</th><th>Nome</th><th width="210">E-mail</th><th>Cidade</th></tr></thead><tbody><tr><td>001D000000kL4p1</td><td>Alice</td><td>alice@company.com</td><td><strong>Berlim</strong></td></tr><tr><td>001D000000kL4p2</td><td>Bob</td><td><strong>bobNew@company.com</strong></td><td>Londres</td></tr><tr><td>001D000000kL4p3</td><td>Charlie</td><td>charlie@company.com</td><td>Paris</td></tr><tr><td>001D000000kL4p4</td><td><strong>Dave</strong></td><td><strong>dave@company.com</strong></td><td><strong>Seattle</strong></td></tr></tbody></table>

**Registros de Contato da org de destino**

<table><thead><tr><th width="200.33331298828125">ID</th><th>Nome</th><th width="210">E-mail</th><th>Cidade</th></tr></thead><tbody><tr><td>002D000000kL5p1</td><td>Alice</td><td>alice@company.com</td><td>Nova York</td></tr><tr><td>002D000000kL5p2</td><td>Bob</td><td>bob@company.com</td><td>Londres</td></tr><tr><td>002D000000kL5p3</td><td>Charlie</td><td>charlie@company.com</td><td>Paris</td></tr></tbody></table>

### Migração de dados com mapeamento automático de registros

#### Cenário bem-sucedido

Neste cenário, uma migração anterior já havia criado um mapeamento automático entre as orgs de origem e de destino. A tabela abaixo mostra esse mapeamento.

| Nome de origem | ID de origem    | ID de destino   |
| -------------- | --------------- | --------------- |
| Alice          | 001D000000kL4p1 | 002D000000kL5p1 |
| Bob            | 001D000000kL4p2 | 002D000000kL5p2 |
| Charlie        | 001D000000kL4p3 | 002D000000kL5p3 |

Quando a migração é executada, o mapeamento automático de registros procura o ID de cada registro de origem no mapeamento existente. Os registros com um mapeamento armazenado são atualizados na org de destino, e os registros sem um mapeamento são inseridos como novos registros. O diagrama e a tabela abaixo ilustram esse processo e as ações resultantes na org de destino.

<figure><img src="https://3756291079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvaxzColPOlNbsq4imqpd%2Fuploads%2FaIMfSu7i6GDBlAQuOiXT%2F3_VEID%20Record%20Mapping%20Example.png?alt=media&amp;token=0db00575-fe39-412d-972b-ad5857d23307" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="179.66668701171875">ID</th><th>Nome</th><th width="210">E-mail</th><th>Cidade</th><th>Operação</th></tr></thead><tbody><tr><td>002D000000kL5p1</td><td>Alice</td><td>alice@company.com</td><td><strong>Berlim</strong></td><td>ATUALIZAR</td></tr><tr><td>002D000000kL5p2</td><td>Bob</td><td><strong>bobNew@company.com</strong></td><td>Londres</td><td>ATUALIZAR</td></tr><tr><td>002D000000kL5p3</td><td>Charlie</td><td>charlie@company.com</td><td>Paris</td><td>ATUALIZAR</td></tr><tr><td>002D000000kL5p4</td><td><strong>Dave</strong></td><td><strong>dave@company.com</strong></td><td><strong>Seattle</strong></td><td>INSERIR</td></tr></tbody></table>

Em seguida, é adicionado um novo mapeamento automático para o registro recém-inserido:

| Nome de origem | ID de origem    | ID de destino   |
| -------------- | --------------- | --------------- |
| Dave           | 001D000000kL4p4 | 002D000000kL5p4 |

#### Cenário com falha

Neste cenário, uma migração anterior já havia criado um mapeamento automático entre as orgs de origem e de destino; no entanto, apenas dois registros estavam mapeados naquela época. A tabela abaixo mostra esse mapeamento.

| Nome de origem | ID de origem    | ID de destino   |
| -------------- | --------------- | --------------- |
| Alice          | 001D000000kL4p1 | 002D000000kL5p1 |
| Bob            | 001D000000kL4p2 | 002D000000kL5p2 |

Antes da próxima migração, uma ferramenta externa adiciona um registro para Charlie tanto na org de origem quanto na org de destino. Quando a migração é executada, o Automático procura o ID de cada registro de origem no mapeamento existente, atualizando os registros de destino que já têm um mapeamento e inserindo novos registros para os que não têm.

O diagrama e a tabela abaixo ilustram esse processo e as ações resultantes na org de destino. Como não existe mapeamento automático para Charlie, a migração insere um registro duplicado, mostrado na linha adicional inserida.

<figure><img src="https://3756291079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvaxzColPOlNbsq4imqpd%2Fuploads%2FyGETlsSHDtegUt29M7Lp%2F4_VEID%20Record%20Mapping%20Example%20-%20Failed.png?alt=media&amp;token=b651fbc8-e7d2-4747-be3c-0b9670ce2624" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="180.33331298828125">ID</th><th>Nome</th><th width="209.666748046875">E-mail</th><th>Cidade</th><th>Operação</th></tr></thead><tbody><tr><td>002D000000kL5p1</td><td>Alice</td><td>alice@company.com</td><td><strong>Berlim</strong></td><td>ATUALIZAR</td></tr><tr><td>002D000000kL5p2</td><td>Bob</td><td><strong>bobNew@company.com</strong></td><td>Londres</td><td>ATUALIZAR</td></tr><tr><td>002D000000kL5p3</td><td>Charlie</td><td>charlie@company.com</td><td>Paris</td><td></td></tr><tr><td><mark style="color:$danger;"><strong>002D000000kL5p4</strong></mark></td><td><mark style="color:$danger;"><strong>Charlie</strong></mark></td><td><mark style="color:$danger;"><strong>charlie@company.com</strong></mark></td><td><mark style="color:$danger;"><strong>Paris</strong></mark></td><td><mark style="color:$danger;"><strong>INSERIR</strong></mark></td></tr><tr><td>002D000000kL5p5</td><td><strong>Dave</strong></td><td><strong>dave@company.com</strong></td><td><strong>Seattle</strong></td><td>INSERIR</td></tr></tbody></table>

Em seguida, dois novos mapeamentos automáticos são adicionados para os registros recém-inseridos:

| Nome de origem | ID de origem    | ID de destino   |
| -------------- | --------------- | --------------- |
| Charlie        | 001D000000kL4p3 | 002D000000kL5p4 |
| Dave           | 001D000000kL4p4 | 002D000000kL5p5 |

{% hint style="warning" %}
A migração falhou porque uma ferramenta externa adicionou Charlie tanto na org de origem quanto na org de destino sem criar um mapeamento automático entre eles. Sem mapeamento para Charlie, o Automático inseriu um novo registro na org de destino em vez de atualizar o existente, resultando em uma duplicata.
{% endhint %}

### Migração de dados com mapeamento manual de registros

#### Cenário bem-sucedido

Chave do campo Manual: `Nome`

Neste cenário, o mapeamento manual de registros corresponde aos registros usando a chave configurada. Com `Nome` como chave Manual, o sistema gera uma chave para cada registro de origem e consulta a org de destino em busca de uma correspondência. Os registros que retornam exatamente uma correspondência são atualizados, e os registros que não retornam correspondência são inseridos. O diagrama e a tabela abaixo ilustram o processo de mapeamento manual de registros e as ações resultantes na org de destino.

<figure><img src="https://3756291079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvaxzColPOlNbsq4imqpd%2Fuploads%2FeN0MzVUkDxLyb4oaEEok%2F1_CEID%20Record%20Mapping%20Example.png?alt=media&amp;token=6a6b92f2-6cde-457c-90cf-bca80edd8701" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="180.3333740234375">ID</th><th>Nome</th><th width="209.6666259765625">E-mail</th><th>Cidade</th><th>Operação</th></tr></thead><tbody><tr><td>002D000000kL5p1</td><td>Alice</td><td>alice@company.com</td><td><strong>Berlim</strong></td><td>ATUALIZAR</td></tr><tr><td>002D000000kL5p2</td><td>Bob</td><td><strong>bobNew@company.com</strong></td><td>Londres</td><td>ATUALIZAR</td></tr><tr><td>002D000000kL5p3</td><td>Charlie</td><td>charlie@company.com</td><td>Paris</td><td>ATUALIZAR</td></tr><tr><td>002D000000kL5p4</td><td><strong>Dave</strong></td><td><strong>dave@company.com</strong></td><td><strong>Seattle</strong></td><td>INSERIR</td></tr></tbody></table>

#### Cenário com falha

Chave do campo Manual: `Nome` + `E-mail`

Neste cenário, o mapeamento manual de registros usa `Nome` + `E-mail` como a chave configurada. Para cada registro de origem, o sistema gera essa chave e consulta a org de destino em busca de correspondência. Como o registro de origem de Bob tem um novo valor em um dos campos da chave, ele não corresponde mais ao registro dele na org de destino.

Os registros que retornam exatamente uma correspondência são atualizados, e os registros sem correspondência são inseridos. O diagrama e a explicação abaixo mostram o processo de mapeamento manual de registros e as ações resultantes na org de destino. Como a chave de Bob na origem não corresponde mais ao registro existente no destino, a migração insere uma duplicata, mostrada na linha adicional inserida.

<figure><img src="https://3756291079-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvaxzColPOlNbsq4imqpd%2Fuploads%2FOSRDO54tfxS7GfSUJKvq%2F2_CEID%20Record%20Mapping%20Example%20-%20Failed.png?alt=media&amp;token=f1fdb64e-0820-4337-94c4-cdea43f3633b" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="180.33331298828125">ID</th><th>Nome</th><th width="210.3333740234375">E-mail</th><th>Cidade</th><th>Operação</th></tr></thead><tbody><tr><td>002D000000kL5p1</td><td>Alice</td><td>alice@company.com</td><td><strong>Berlim</strong></td><td>ATUALIZAR</td></tr><tr><td>002D000000kL5p2</td><td>Bob</td><td>bob@company.com</td><td>Londres</td><td></td></tr><tr><td>002D000000kL5p3</td><td>Charlie</td><td>charlie@company.com</td><td>Paris</td><td>ATUALIZAR</td></tr><tr><td><mark style="color:$danger;"><strong>002D000000kL5p4</strong></mark></td><td><mark style="color:$danger;"><strong>Bob</strong></mark></td><td><mark style="color:$danger;"><strong>bobNew@company.com</strong></mark></td><td><mark style="color:$danger;"><strong>Londres</strong></mark></td><td><mark style="color:$danger;"><strong>INSERIR</strong></mark></td></tr><tr><td>002D000000kL5p5</td><td><strong>Dave</strong></td><td><strong>dave@company.com</strong></td><td><strong>Seattle</strong></td><td>INSERIR</td></tr></tbody></table>

{% hint style="warning" %}
A migração falhou porque o `E-mail` valor mudou na org de origem depois que o registro de destino foi criado. Como `E-mail` faz parte da chave Manual, a nova chave gerada a partir do registro de origem (`Bob` + `bobNew@company.com`) não correspondeu mais à chave do registro existente de destino (`Bob` + `bob@company.com`). Sem encontrar correspondência, o Manual inseriu um novo registro na org de destino em vez de atualizar o existente, resultando em uma duplicata.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flosum.com/data-migrator/data-migrator-pt-br/modelos/migracao/como-o-mapeamento-de-registros-funciona.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.