Rajeev Pentyala – Microsoft Power Platform

Alternative Keys are useful to retrieve or update the records without the need of GUID. It avoids the overhead of retrieving record’s GUID while update operation.

In conventional way, to update an Account record from external web application, you would need to get the GUID first and then update.

With alternate key, you can configure any of your field of type (Single Line of Text, Whole Number or Decimal Number) as Alternate key and use instead of GUID to retrieve or update.

We can have up to 5 different alternate keys per entity.

Sample C# code to update record with out GUID:

• I configured “Account Number” as alternate key.
• I have an Account with ‘Account Number’ as ‘Acct123’ and below is the code to update record. Notice that I did not provide the record GUID.

Entity account = new Entity(“account”, “accountnumber”, “Acct123”);
account[“name”] = “Rajeev Modified”;
service.Update(account);

Create an Alternate key

• Go to Customization–> Entity–> Keys –> New

Create Alternate Key

• Click “Ok”
• Wait for few seconds so that the background workflow complete creation of required indexes.

Jscript to retrieve using Alternate key:

• Below is the script to retrieve a record with alternate key using web api.

function getAccountByAlternateKey() {
try {
var clientUrl = Xrm.Page.context.getClientUrl();
var req = new XMLHttpRequest();
// Account Number as an ‘Alternate key’
req.open(“GET”, encodeURI(clientUrl + “/api/data/v8.0/accounts(accountnumber=’Acct123′)“), true);
// If multiple keys as ‘Alternate key’
//req.open(“GET”, encodeURI(clientUrl + “/api/data/v8.0/accounts(name=’Rajeev’,emailaddress1=’rajeev@live.com’)”), true);
req.setRequestHeader(“Accept”, “application/json”);
req.setRequestHeader(“Content-Type”, “application/json; charset=utf-8”);
req.setRequestHeader(“OData-MaxVersion”, “4.0”);
req.setRequestHeader(“OData-Version”, “4.0”);
req.onreadystatechange = function () {
if (this.readyState == 4 /* complete */) {
req.onreadystatechange = null;
if (this.status == 200) {
var data = JSON.parse(this.response);
var dat = data.value;
for (var i = 0; i < dat.length; i++) {
var accountId = dat[i].accountid;
Xrm.Utility.alertDialog(“Account Id : ” + accountId);
}
}
else {
var error = JSON.parse(this.response).error;
alert(“Error retrieving Account- ” + error.message);
}
}
};

req.send();
} catch (e) {
alert(“Error in getAccountByAlternateKey – ” + e.description);
}
}

JScript to Update Record Using Alternate Key

function updateAccountByAlternateKey() {
try {
var clientUrl = Xrm.Page.context.getClientUrl();
var req = new XMLHttpRequest();
// Account Number as an ‘Alternate key’
req.open(“PATCH“, encodeURI(clientUrl + “/api/data/v8.0/accounts(accountnumber=’Acct123′)“), true);
req.setRequestHeader(“Accept”, “application/json”);
req.setRequestHeader(“Content-Type”, “application/json; charset=utf-8”);
req.setRequestHeader(“OData-MaxVersion”, “4.0”);
req.setRequestHeader(“OData-Version”, “4.0”);
req.onreadystatechange = function () {
if (this.readyState == 4 /* complete */) {
req.onreadystatechange = null;
if (this.status == 204) {
var accountUri = this.getResponseHeader(“OData-EntityId”);

//get EntityId from ResponseHeader of Created Record
var accountID = accountUri.split(/[()]/);
accountID = accountID[1];

Xrm.Utility.alertDialog(“Updated Account ID : ” + accountID);
}
}
};

// Set Account Object
var objAccount = {};
objAccount.name = “Rajeev Modified”;
objAccount.revenue = 123456;

//convert JSON object to string
var body = JSON.stringify(objAccount);

req.send(body);
} catch (e) {
alert(“Error in updateAccountByAlternateKey – ” + e.description);
}
}

Refer article  for more details.

🙂