Utilizando Alternative Keys para atualização de registros no Dataverse

Normalmente quando estamos trabalhando com integrações entre um sistema e o Dataverse, sempre alinhamos que os dados devem ter um campo chave a fim de ter sua identificação única, permitindo que a troca de informações seja integra.

Durante essa integração, normalmente realizamos uma consulta para localizar o registro pelo campo chave definido, e caso localizado, utilizamos o GUID do registro para atualizar e se não encontrado cria-se o registro.

Essa é uma abordagem tradicional, porém podemos ter uma outra abordagem onde não ficamos presos no uso do GUID do registro. E podemos fazer isso através das “Alternative Keys” que existem na configuração de tabela no Dataverse.

Alternative Key

Como o próprio nome diz, são chaves alternativas afim de identificar única e exclusivamente o registro com os dados, sem necessidade de saber o GUID do registros. Podemos por exemplo utilizar o CPF na tabela de contato, dizendo que irá ter um um único exclusivo registro de CPF. E se o usuário tentar cadastrar mais um registro com o mesmo CPF, o sistema irá informar que já existe um registro com a chave informada.

A tabela abaixo descreve quais tipos de campos podem ser utilizados como chave

Outro ponto importante é que o campo utilizado não pode ter segurança de campo habilitada, o dado da coluna necessita ser visível por todos.

Criando Alternative Keys

Para criar o processo é bem simples, você precisa ser Administrador do Sistema ou Customizador para poder alterar as tabelas do Dataverse.

Abra o make.powerapps.com e selecione seu ambiente, após selecione a solução que contém a sua tabela, selecione a tabela e selecione “Keys”.

Agora na barra superior vamos utilizar a opção + New Key (Nova Chave) para registrar uma nova chave.

Com o formulário aberto Informe o nome de exibição da key e o seu nome lógico. Após isso, selecione um ou mais campos que devem fazer parte da sua chave.

Agora que já criamos a key, vamos então cadastrar alguns registros. Nesse exemplo que estamos utilizado temos a tabela veículo onde temos o campo “Placa” e definimos como chave.

Vamos criar dois registros para testes

Vamos agora atualizar um dos registro mudando o campo “Estado”, porém não vamos utilizar o GUID do registro, mas sim a identificação da placa, vamos atualizar a placa IVV-2987.

var record = {};
record.mfp_estado = "Parana"; // Text

$.ajax({
	type: "PATCH",
	url: Xrm.Utility.getGlobalContext().getClientUrl() + "/api/data/v9.2/mfp_veiculos(mfp_placa='IVV-2987')",
	async: true,
	headers: {
		"OData-MaxVersion": "4.0",
		"OData-Version": "4.0",
		"Content-Type": "application/json; charset=utf-8",
		"Accept": "application/json",
		"Prefer": "odata.include-annotations=*"
	},
	data: JSON.stringify(record),
	success: function (data, textStatus, xhr) {
		console.log("Record updated");
	},
	error: function (xhr, textStatus, errorThrown) {
		console.log(xhr);
	}
});

Como você pode ver no código javascript apresentando quando informamos a tabela mfp_veiculos, incluímos também na requisição o nome lógico do campo (mfp_placa) juntamente com o valor IVV-2987.
Dessa forma, o Dataverse vai internamente validar e atualizar o registro com base nas alterantive keys definidas anteriormente.

Quando executo o código tenho o resultado esperado.

Interessante né?! Dessa forma, podemos garantir a integridade do dados sem a necessidade de obter o GUID do registro. Gerando uma comunicação mais fluída entre sistemas, e em muitas vezes não obrigando o sistema externo a ter o conhecimento dos IDs dos registros no Dataverse.

Além disso, as chaves alternativas podem ser utilizadas também para você aplicar relacionamento entre tabelas, se você tiver que relacionar uma tabela com outra e ela tem uma key, você pode utilizar o valor da key para fazer o vínculo. Como no exemplo abaixo:

\mfp_veiculos(IXI-0387)

Ao utilizar essa denotação em um requisição de webapi ou até mesmo no Power Automate, o sistema irá usar a chave para fazer o relacionamento ao invés do GUID.

Espero que tenham gostado de mais essa dica! Até o próximo post!