v2.3.0

Bigger minor release than usual with new features! 🙂

Search API v2.0 🎉

The library now fully supports a Search API v2.0 with query (previously known as search)¹, suggest and autocomplete functions!

Requests for v1 and v2 are almost fully compatible ². I had to adjust the library's API slightly to include new features in Search 2.0 and because of that you will see "legacy" properties marked as deprecated to encourage the use of the new properties. If you don't want to use the new syntax and stick with v1, it's fine, just beware that the new features that got introduced in v2 are not going to be available in v1.

Responses by default are not compatible between v1 and v2. But it's possible to enable the compatibility by setting enableResponseCompatibility to true:

const webApi = new DynamicsWebApi({
    searchApi: {
        // version: "2.0",
        options: {
            enableResponseCompatibility: true
        }
    }
})

Important

I would recommend enabling this option only temporarily, just to test if your code is fully compatible with 2.0 or to rewrite your v1 code to v2 without switching your Search API version (by keeping version: "1.0") and deal with all incompatibility errors later. The main reason is because it will consume more memory and cpu power by duplicating all properties in responses to achieve a full compatibility.

Also note that the search function is renamed to query and is marked as deprecated.

All deprecated features will be removed in the next major version.

Background Operations 🎉

Note

This feature is currently in preview in an official documentation and is only supported when calling custom APIs.

Background operations are now supported in DynamicsWebApi.

"Use background operations to send requests that Dataverse processes asynchronously. Background operations are useful when you don't want to maintain a connection while a request runs."

DynamicsWebApi supports calls to the Status Monitor resource, as well as regular requests to the backgroundoperations table. For more info check the documentation.

Summary

Changes

• Search API: Added support for Search API v2.0 for query, suggest and autocomplete functions. Simply change a version in the searchApi configuration to 2.0 to start using it.
• Search API: Special symbols in a search term can now be automatically escaped if the Search API's config option escapeSpecialCharacters is set as true (it works for both v1 and v2):

const dynamicsWebApi = new DynamicsWebApi({
  searchApi: {
    options: { escapeSpecialCharacters: true }
  }
});

• Search API: Added a new option to enable Search API v1 and v2 response compatibility: enableResponseCompatibility.
• Background Operations: Added support for background operations respondAsync: true. This feature is still in preview in official documentation. Currently respondAsync is available for a callAction and works only for custom api actions.
• Background Operations: Added support for a Status Monitor service. Note, that it is NOT a Dataverse Web API service and has a different behavior (requests, responses, errors, etc).
• Background Operations: Background operation callback URL can be set by default in the configuration, or per each request: backgroundOperationCallbackUrl.
• Background Operations: BackgroundOperationResponse type can be used in a TResponse to get a strongly typed background operation response.
• Added a new request parameter tag. It can be used to pass a shared variable to a custom plugin. More Info.
• Added TResponse to create, update and upsert functions. By default, it would still return TData unless specified otherwise. This is done to avoid a breaking change in the types. Normally, all those operations would not return TData, unless returnRepresentation is set to true. This 2nd template parameter is added as a workaround. In the future there will possibly be a more solid solution.
• General refactoring of the codebase.

Fixes

• returnRepresentation and useEntityNames would not be overwritten by false if their values were true when using setConfig function.
• prefer option now accepts custom prefer values, not only the ones that are supported by the library.

Feel free to let me know about any bugs, issues or suggestions. Thank you! ❤️

---

1. I made a decision to rename search into query just to align with Microsoft's official Search API documentation. We will see if this was a mistake in the future. 🙂 ↩

2. Microsoft has changed filter syntax. Therefore, if your v1 Search API requests were heavily relying on filters, most likely your v2 requests would fail. You can try it by temporarily switching to 2.0 and setting enableResponseCompatibility to true in a searchApi config. Check documentation for more info. ↩

v2.2.1

Fixes

• Wrong line endings in the batch request resulted in InnerException : System.ArgumentException: Stream was not readable when inChangeSet was set to false. #183

v2.2.0

Changes

• ⚠️ Dropping official support for Node.js v16. Mainly because I cannot run actions with that version anymore, so I cannot guarantee that any future changes will continue working in it.
• Replaced a custom UUID generator function with a built-in randomUUID (Crypto API).
  ⚠️ This may cause issues in the older browsers, and the library must now run in the "Secure Context" (https).
• Slightly optimized dateReviver function.

Fixes

• Modified expand property in the type definitions to accept a string. It could always accept a string together with an array of expand objects.

v2.1.7

Fixes:

• Wrong type declaration for UploadRequest and DownloadRequest: property and fieldName should be optional, until fieldName is removed.

Changes:

• Additional optimizations of regular expressions.

v2.1.6

Changes

• ⚠️ Deprecated: fieldName in request properties for deleteRecord, uploadFile, downloadFile. Please use property instead.
• Curly brackets won't be removed from the GUIDs inside filter if the value that contains the GUID is inside single quotes, which means it's a string. This is an improvement of an existing functionality.
  Before: "attribute eq 'some text {GUID} more text'" would result in "attribute eq 'some text GUID more text'"
  Now: "attribute eq 'some text {GUID} more text'" stays the same "attribute eq 'some text {GUID} more text'"
• Improving performance by pre-compiling and optimizing regular expressions.
• General refactoring to improve code readability.

v2.1.5

Fixes

• Missing authorization token when request with a long URL is converted into a Batch request. #175

v2.1.4

Fixes

• name property in a callFunction must be optional, until functionName is removed.

v2.1.3

Changes:

• Added support for composable functions. Request object in callFunction now accepts select and filter parameters. #168
• ContentId can be used as an URI reference inside the Batch Request. For example:

dynamicsWebApi.startBatch();

dynamicsWebApi.create({
  contentId: "1", //<-- this content id will be used in the next request
  collection: "contacts",
  data: {
    firstname: "James",
    lastname: "Doe"
  }
});

dynamicsWebApi.updateSingleProperty({
  contentId: "$1", //<-- using content id of the record created in a previous request
  // note, that neither "collection" nor "key" is used in this request, 
  // contentId replaces those
  fieldValuePair: { lastname: "Bond" }
});

const results = await dynamicsWebApi.executeBatch();
//results[0] will have an id of a contact record
//results[1] will be empty

Deprecations:

• functionName parameter in callFunction is marked as deprecated and will be removed in one of the future versions. Please use name instead.

v1.7.12

Changes:

• Added a skipNameCheck for composable functions workaround #168

v2.1.2

Changes:

• Added @odata.nextLink, @odata.count and @odata.deltaLink to TypeScript definitions.

Fixes:

• Duplicate query parameters during pagination with nextPageLink parameter in retrieveMultiple. #164
• Duplicate serverUrl in a request url during pagination with nextPageLink parameter in retrieveMultiple. This only happened if serverUrl in DynamicsWebApi config had a closing slash. #164