WebApiRecord
Records returned from the Hsl.WebApi retrieve methods will have properties for each selected attribute as well as the methods defined below.
interface WebApiRecord {
getValue(propertyName: string): any;
getFormattedValue(propertyName: string): string | null;
getLookupLogicalName(propertyName: string): string | null;
getRecordReference(attributeName: string): RecordReference | null;
[attributeNameOrNavigationProperty: string]: any;
}
getValue
Gets the value of the specified property. This method will throw an error if the property doesn't exist. This can help guard against code issues like field name types.
⚠️ getValue will not throw an error for unknown properties for fetchXml queries or when
allowUnknownGet
is set.
function retrieveGetValueSample() {
const client = Hsl.WebApi.getClient('9.1');
return client.retrieve({ entityType: 'account', id: '7fb47cc4-fa9a-4048-a455-5e7a58d0a319' }, ['accountnumber']).then(record => {
const accountNumberBad = record.getValue('accountnmber'); // Throws an error due to incorrect field name.
const accountNameBad = record.getValue('name'); // Throws because 'name' wasn't selected.
// These yield the same result
const accountNumber1 = record.accountnumber;
const accountNumber2 = record.getValue('accountnumber');
});
}
function getValueUnknownPropertySample() {
const client = Hsl.WebApi.getClient({
apiVersion: '9.1',
allowUnknownGet: true,
});
return client.retrieve({ entityType: 'account', id: '7fb47cc4-fa9a-4048-a455-5e7a58d0a319' }, ['accountnumber']).then(record => {
const accountNumberBad = record.getValue('accountnmber'); // returns null despite unknown field name
const accountNameBad = record.getValue('name'); // returns null despite name not being selected.
// These yield the same result
const accountNumber1 = record.accountnumber;
const accountNumber2 = record.getValue('accountnumber');
});
}
function getValueFetchSample() {
const client = Hsl.WebApi.getClient('9.1');
return client.fetch("<fetch><entity name='account'><attribute name='accountnumber' /></entity></fetch>").then(fetchResult => {
const record = fetchResult.value[0];
if (record) {
const accountNumberBad = record.getValue('accountnmber'); // returns null despite unknown field name
const accountNameBad = record.getValue('name'); // returns null despite name not being selected.
const accountNumber1 = record.accountnumber; // undefined - results for FetchXml queries omit null values instead of including them as null in the result.
const accountNumber2 = record.getValue('accountnumber'); // null
}
});
}
getFormattedValue
Gets the formatted value of the given property if available otherwise the string value of the field or null. This is the value of the field appropriate for displaying to end users.
⚠️ This method is only available if formattedValues or annotations is set in GetRequestSettings.
function retrieveGetFormattedValueSample() {
const client = Hsl.WebApi.getClient('9.1');
return client.retrieve({ entityType: 'account', id: '7fb47cc4-fa9a-4048-a455-5e7a58d0a319' }, ['accountnumber', 'industrycode', '_primarycontactid_value'], undefined, { formattedValues: true }).then(record => {
const accountNumber = record.getFormattedValue('accountnumber');
const industryName = record.getFormattedValue('industrycode');
const primaryContactName = record.getFormattedValue('_primarycontactid_value');
});
}
getRecordReference
Gets a reference for the specified lookup attribute. Returns null if the attribute is null.
See RecordReference
⚠️ This method is only available if annotations is set to '*' in GetRequestSettings.
function getRecordReferenceSample() {
const client = Hsl.WebApi.getClient('9.1');
return client.retrieve({ entityType: 'account', id: '7fb47cc4-fa9a-4048-a455-5e7a58d0a319' }, ['_primarycontactid_value'], undefined, {
annotations: '*',
}).then(record => {
const primaryContact = record.getRecordReference('primarycontactid');
if (primaryContact !== null) {
console.log(primaryContact.entityType);
console.log(primaryContact.id);
console.log(primaryContact.name);
Xrm.Page.getAttribute('hsl_contactid').setValue([primaryContact]);
}
});
}
getLookupLogicalName
Gets the logical name of the specified lookup attribute. Returns null if the attribute is null.
⚠️ This method is only available if annotations is set to '*' in GetRequestSettings.
Parsing Values
Depending on the data type of the field, the value may need parsing. See below for samples on what's returned and how to parse it.
function dataParsingSample() {
const client = Hsl.WebApi.getClient('9.1');
// This sample is for update but you'll want to do the same thing for create/upsert.
client.retrieve({ entityType: 'account', id: 'adaaa79b-4054-4035-8cf4-b627571e1397' }, null /* Avoid all columns in real world scenarios */, {
primarycontactid: ['createdon'],
}).then(record => {
// string types have a regular javascript string.
const hsl_string = record.getValue('hsl_string');
const hsl_memo = record.getValue('hsl_memo');
// Numeric types have a regular javascript number.
// Use record.getFormattedValue to get the formatted string.
const hsl_wholenumber = record.getValue('hsl_wholenumber');
const hsl_floatingpoint = record.getValue('hsl_floatingpoint');
const hsl_decimal = record.getValue('hsl_decimal');
const hsl_money = record.getValue('hsl_money');
// picklist fields give the numeric value of the field. Use record.getFormattedValue('hsl_picklist') to get the label.
const hsl_picklist = record.getValue('hsl_picklist');
// Multiselect picklists return a number array. Ex: [296010001, 296010005]
const hsl_multiselect = record.getValue('hsl_multiselect');
// Two option fields give a boolean value.
const hsl_boolean = record.getValue('hsl_boolean');
// Use parseDateOnly for date only behavior fields (getValue will return a string formatted YYYY-MM-DD).
const hsl_dateonly = record.parseDateOnly('hsl_dateonly');
// Use parseDateTime for fields with user local (getValue will return a string formatted YYYY-MM-DDTHH:mm:ssZ 2020-08-03T14:50:23Z)
const hsl_datetimeuserlocal = record.parseUserLocalDate('hsl_datetimeuserlocal');
// Use parseDateTime for fields with time zone independent behavior. (getValue will return a string formatted YYYY-MM-DDTHH:mm:ssZ 2015-01-01T22:35:00Z)
const hsl_datetimetzi = record.parseTziDate('hsl_datetimetzi');
// Image - note: images loaded by retrieve requests are just a thumbnail. Use client.downloadFile to load the full image.
const hsl_imageBase64 = record.getValue('hsl_image');
// Use client.downloadFile to download a file attribute.
// getValue will return the primary id for a lookup.
const primaryContactId = record.getValue('_primarycontactid_value');
// getRecordReference returns an object like { entityType: 'contact', id: '14221998-a02c-4874-afe0-6ce6b8974a66', name: 'John Smith' }
const primaryContactReference = record.getRecordReference('_primarycontactid_value');
// getLookupLogicalName returns 'contact'.
const primaryContactType = record.getLookupLogicalName('_primarycontactid_value');
// Returns the primary name of the related record. In this case the fullname attribute.
const primaryContactName = record.getFormattedValue('_primarycontactid_value');
// get expanded navigation property.
const primaryContact = record.getValue('primarycontactid');
// Helper methods work on expanded properties.
const primaryContactCreated = primaryContact && primaryContact.parseUserLocalDate('createdon');
});
}