Upgrading from version 8 to 9 of the JavaScript Library

General

  • Hsl.Dialog.confirm and Hsl.Dialog.alert now return promises instead of having function passed as parameter. No longer accept dialog options.
  • DialogOptions content setting for Hsl.Dialog.open and related methods is now contentHtml
  • Hsl.enumHasFlag removed. Use (enumValue & flag) === flag; instead.
  • Hsl.lookup is now Hsl.Dialog.lookup and now returns a Promise instead of using a callback parameter.

Form

Due to the Xrm.Page deprecation, most methods relating to the form were moved to be on a new FormContext class. For more details see Using Form Context

  • Form.getRecordId and LookupAttribute.getValue (and related methods like getValueId) now return guids in all lower case.
  • LookupAttribute setSingleValue no longer accepts an EntityReference and only takes a RecordReference.
  • Many methods are removed. See the Documentation for details on what remains.

Using the FormContext

Form code that referenced Hsl.Form will need to replace calls to methods of global Hsl.Form with methods using the local FormContext.

So code like this for the v8 version of the library:

function hsl_accountOnLoad(e) {
    const nameAttribute = Hsl.attribute('hsl_name');
    nameAttribute.setVisible(false);
    const nameValue = nameAttribute.getValue();
}

Now needs to use methods on the Hsl.FormContext object returned from Hsl.form.

function hsl_accountFormOnLoad(ctx) {
    const form = Hsl.form(ctx);
    const nameAttribute = form.attribute('hsl_name');
    nameAttribute.setVisible(false);
    const nameValue = nameAttribute.getValue();
}

⚠️ When registering the on load event in the form editor, be sure to check "Pass execution context as first parameter"

WebApi

  • Hsl.WebApi.client now defaults to version 9 of the WebApi endpoint and the equivalent of Hsl.WebApi.getClient('9.0'). For backwards compatibility, you can set Hsl.WebApi.client = Hsl.WebApi.getClient('8.0') which will change the default client for all scripts on the current page.
  • Not specifying a select list for retrieve or expand will now result in an error. Specify null to select all columns.
  • bulkRetrieveByIds, fetchAll, and queryAll now support synchronous execution.
  • Hsl.WebApi.encodeEntityType and Hsl.WebApi.bindReference now return a placeholder object
  • Added new useNonStandardSyncPromise setting.
  • Hsl.currentUser redone. See documentation page (TODO: add link) for details. It is now part of the main library.core.js and no longer part of the library.orgservice.js file.
  • Added Hsl.WebApi.executeService. Works similar to Hsl.OrgService.executeService but only supports execution using custom actions. Doesn't support retrieve or create.
  • Overloads using CollectionReference or AlternateKeyLookupReferenceCollection that reference the webapi collection name like client.create({ collectionName: 'accounts' }, { name: 'abc' }) are removed. Use the overloads referencing the entity logical name instead. client.create('account', { name: 'abc' })
  • Methods on the retrieved records (getValue, getFormattedValue, getLookupLogicalName, and getRecordReference) now throw an error for properties not included in the select list. Ex: if you retrieve just the 'name' property of an account, record.getValue('accountnumber') will throw an error instead of returning null. Use 'accountnumber' in record to determine whether it contains a particular property. For compatibility with older versions, use the allowUnknownGet setting of Hsl.WebApi.getClient.
  • createAndGet, updateAndGet, and upsertAndGet now allow specifying formattedValues: true or annotations: '*'.
  • FetchXml is now minified prior to passing it to the web service (excess whitespace and xml comments are removed).

Removed Functionality

  • Hsl.Cloning - This has been split off into its own separate solution. See the documentation for Hsl Hierarchy Cloning for details on upgrading.
  • Hsl.OrgData (library.legacyodata.js). Used for connecting to the 2011 oData v2 endpoint.
  • CEI (library.legacycei.js)
  • jQuery - Hsl.$, Hsl.jQuery, hsl.jquery.js file. JQuery is still available through the dialog context when using Hsl.Dialog but if you need it elsewhere, create a custom web resource to use jQuery https://jquery.com/download/.
  • JQuery UI - loadJQueryUI in Hsl.Dialog and jquery-ui-modified.js file. You can load jQuery UI yourself using loadScriptResource and the contentCss setting of the Dialog options.
  • Removed getCopyright, getMajorVersion, getMinorVersion, getPatchVersion
  • Hsl.Console - use standard console methods with string substitutions. https://developer.mozilla.org/en-US/docs/Web/API/Console
  • Hsl.Client
  • Hsl.newGuid, Hsl.normalizeGuid, Hsl.guidEquals - use Hsl.Guid.getNew, Hsl.Guid.normalize, and Hsl.Guid.equals.
  • DateAttributeClass setToUtcNeutral, setToNoonUtc, normalizeDate, normalizeDateOnChange - use date only behavior instead.
  • Hsl.getOrganizationServiceUrl - SOAP Endpoint is deprecated.
  • Hsl.fieldSet
  • createFieldSet
  • Hsl.getCompanyName, Hsl.getProductName
  • Hsl.Notification
  • LookupAttributeClass.setViewSelectorEnabled
  • Hsl.WebResource.createUrl no longer accepts boolean as the third parameter to 'passParams'. It now takes a form context which, if passed, is used to build parameters.
  • Hsl.Tooltips, FieldSet.setTooltip
  • Hsl.Validation
  • Hsl.tab, Hsl.tabSet, Hsl.section, Hsl.sectionSet
  • Hsl.getEntityTypeCode, Hsl.getEntityNameFromTypeCode
  • Hsl.getContextParametersString
  • Hsl.userInformation, Hsl.teamInformation (Hsl.currentUser still exists but redone)
  • Hsl.List (makeArray, selectMany, unique)
  • Hsl.normalizeDate
  • Form save handlers
  • Hsl.String.format
  • Hsl.dateFormat - most uses can be handled using Intl.DateTimeFormat API (see contructor details for options available)
  • Hsl.Dialog methods openError, openWarning, openInfo, and openHelp. Use Hsl.Dialog.open instead.