add: fetch, fetchAll, executeFetchXmlAll, retrieveAll

Author: AleksandrRogov

README.md

@@ -34,6 +34,7 @@ Any suggestions are welcome!
   * [Disassociate](#disassociate)
   * [Disassociate for a single-valued navigation property](#disassociate-for-a-single-valued-navigation-property)
   * [Fetch XML Request](#fetch-xml-request)
+    * [Fetch All records](#fetch-all-records)
   * [Execute Web API functions](#execute-web-api-functions)
   * [Execute Web API actions](#execute-web-api-actions)
 * [JavaScript Promises](#javascript-promises)
@@ -164,9 +165,9 @@ Basic calls can be made by using functions with most commonly used input paramet
 not provide all possible ways of interaction with CRM Web API (for example, [conditional retrievals](https://msdn.microsoft.com/en-us/library/mt607711.aspx#bkmk_DetectIfChanged)
 are not supported in basic functions).
 
-Basic functions are: `create`, `update`, `upsert`, `deleteRecord`, `retrieve`, `retrieveMultiple`, `count`, `countAll`, `executeFetchXml`, 
-`associate`, `disassociate`, `associateSingleValued`, `disassociateSingleValued`, `executeBoundFunction`, `executeUnboundFunction`, 
-`executeBoundAction`, `executeUnboundAction`.
+Basic functions are: `create`, `update`, `upsert`, `deleteRecord`, `retrieve`, `retrieveMultiple`, `retrieveAll`, `count`, `countAll`, 
+`executeFetchXml`, `executeFetchXmlAll`, `associate`, `disassociate`, `associateSingleValued`, `disassociateSingleValued`, `executeBoundFunction`, 
+`executeUnboundFunction`, `executeBoundAction`, `executeUnboundAction`.
 
 Advanced functions have a suffix `Request` added to the end of the applicable operation. 
 Most of the functions have a single input parameter which is a `request` object.
@@ -568,15 +569,29 @@ dynamicsWebApi.retrieveMultipleRequest(request).then(function (response) {
 
 #### Retrieve All records
 
-Current function goes through all pages automatically.
+The following function retrieves records and goes through all pages automatically.
+
+```js
+//perform a multiple records retrieve operation
+dynamicsWebApi.retrieveAll("leads", ["fullname", "subject"], "statecode eq 0").then(function (response) {
+
+    var records = response.value;
+    //do something else with a records array. Access a record: response.value[0].subject;
+})
+.catch(function (error){
+    //catch an error
+});
+```
+
+OR advanced function:
 
 ```js
 //set the request parameters
 var request = {
     collection: "leads",
     select: ["fullname", "subject"],
     filter: "statecode eq 0",
-    maxPageSize: 5
+    maxPageSize: 5				//just for an example
 };
 
 //perform a multiple records retrieve operation
@@ -714,6 +729,9 @@ dynamicsWebApi.executeFetchXml("accounts", fetchXml).then(function (response) {
 });
 ```
 
+Starting from version 1.2.5 DynamicsWebApi has an alias with a shorter name and same parameters: `dynamicsWebApi.fetch(...)`, 
+that works in the same way as `executeFetchXml`.
+
 #### Paging
 
 ```js
@@ -748,6 +766,28 @@ dynamicsWebApi.executeFetchXml("accounts", fetchXml).then(function (response) {
 //catch...
 ```
 
+#### Fetch All records
+
+The following function executes a FetchXml and goes through all pages automatically:
+
+```js
+var fetchXml = '<fetch mapping="logical">' +
+                    '<entity name="account">' +
+                        '<attribute name="accountid"/>' +
+                        '<attribute name="name"/>' +
+                    '</entity>' +
+               '</fetch>';
+
+dynamicsWebApi.executeFetchXmlAll("accounts", fetchXml).then(function (response) {
+    
+    //do something with results here; access records response.value[0].accountid
+})
+//catch...
+```
+
+Starting from version 1.2.5 DynamicsWebApi has an alias with a shorter name and same parameters: `dynamicsWebApi.fetchAll(...)`, 
+that works in the same way as `executeFetchXmlAll`.
+
 ### Execute Web API functions
 
 #### Bound functions
@@ -822,7 +862,7 @@ dynamicsWebApi.executeUnboundAction("WinOpportunity", actionRequest).then(functi
 ### In Progress
 
 - [ ] overloaded functions with rich request options for all Web API operations.
-- [ ] get all pages requests, such as: countAll, retrieveMultipleAll, fetchXmlAll and etc.
+- [X] get all pages requests, such as: countAll, retrieveMultipleAll, fetchXmlAll and etc. Implemented in v.1.2.5.
 - [ ] "formatted" values in responses. For instance: Web API splits information about lookup fields into separate properties, the config option "formatted" will enable developers to retrieve all information about such fields in a single requests and access it through DynamicsWebApi custom response objects.
 - [ ] Intellisense for request objects.
 

lib/dynamics-web-api-callbacks.js

@@ -652,6 +652,23 @@ function DynamicsWebApi(config) {
         }, successCallback, errorCallback, nextPageLink);
     }
 
+    /**
+     * Sends an asynchronous request to retrieve all records.
+     *
+     * @param {string} collection - The Name of the Entity Collection.
+     * @param {Function} successCallback - The function that will be passed through and be called by a successful response.
+     * @param {Function} errorCallback - The function that will be passed through and be called by a failed response.
+     * @param {Array} [select] - Use the $select system query option to limit the properties returned.
+     * @param {string} [filter] - Use the $filter system query option to set criteria for which entities will be returned.
+     */
+    this.retrieveAll = function (collection, successCallback, errorCallback, select, filter) {
+        return _retrieveAllRequest({
+            collection: collection,
+            select: select,
+            filter: filter
+        }, successCallback, errorCallback);
+    }
+
     /**
      * Sends an asynchronous request to retrieve records.
      *
@@ -741,7 +758,7 @@ function DynamicsWebApi(config) {
      * @param {string} [pagingCookie] - Paging cookie. For retrieving the first page, pagingCookie should be null.
      * @param {string} [impersonateUserId] - A String representing the GUID value for the Dynamics 365 system user id. Impersonates the user.
      */
-    this.executeFetchXml = function (collection, fetchXml, successCallback, errorCallback, includeAnnotations, pageNumber, pagingCookie, impersonateUserId) {
+    var executeFetchXml = function (collection, fetchXml, successCallback, errorCallback, includeAnnotations, pageNumber, pagingCookie, impersonateUserId) {
 
         ErrorHelper.stringParameterCheck(collection, "DynamicsWebApi.executeFetchXml", "collection");
         ErrorHelper.stringParameterCheck(fetchXml, "DynamicsWebApi.executeFetchXml", "fetchXml");
@@ -796,6 +813,39 @@ function DynamicsWebApi(config) {
         _sendRequest("GET", result.url + "?fetchXml=" + encodedFetchXml, null, result.headers, onSuccess, errorCallback);
     }
 
+    this.fetch = this.executeFetchXml = executeFetchXml;
+
+    var _executeFetchXmlAll = function (collection, fetchXml, successCallback, errorCallback, includeAnnotations, pageNumber, pagingCookie, impersonateUserId, records) {
+        var records = records || [];
+
+        var internalSuccessCallback = function (response) {
+            records = records.concat(response.value);
+
+            if (response.PagingInfo) {
+                _executeFetchXmlAll(collection, fetchXml, successCallback, errorCallback, includeAnnotations, response.PagingInfo.nextPage, response.PagingInfo.cookie, impersonateUserId, records);
+            }
+            else {
+                successCallback({ value: records });
+            }
+        };
+
+        executeFetchXml(collection, fetchXml, internalSuccessCallback, errorCallback, includeAnnotations, pageNumber, pagingCookie, impersonateUserId);
+    }
+
+    /**
+     * Sends an asynchronous request to execute FetchXml to retrieve all records.
+     *
+     * @param {string} collection - An object that represents all possible options for a current request.
+     * @param {string} fetchXml - FetchXML is a proprietary query language that provides capabilities to perform aggregation.
+     * @param {Function} successCallback - The function that will be passed through and be called by a successful response.
+     * @param {Function} errorCallback - The function that will be passed through and be called by a failed response.
+     * @param {string} [includeAnnotations] - Use this parameter to include annotations to a result. For example: * or Microsoft.Dynamics.CRM.fetchxmlpagingcookie
+     * @param {string} [impersonateUserId] - A String representing the GUID value for the Dynamics 365 system user id. Impersonates the user.
+     */
+    this.fetchAll = this.executeFetchXmlAll = function (collection, fetchXml, successCallback, errorCallback, includeAnnotations, impersonateUserId) {
+        return _executeFetchXmlAll(collection, fetchXml, successCallback, errorCallback, includeAnnotations, null, null, impersonateUserId);
+    }
+
     /**
      * Associate for a collection-valued navigation property. (1:N or N:N)
      *

lib/dynamics-web-api.js

@@ -630,7 +630,7 @@ function DynamicsWebApi(config) {
      * @returns {Promise}
      */
     this.countAll = function (collection, filter, select) {
-        return this.retrieveAllRequest({
+        return _retrieveAllRequest({
             collection: collection,
             filter: filter,
             select: select
@@ -660,7 +660,23 @@ function DynamicsWebApi(config) {
     }
 
     /**
-     * Sends an asynchronous request to count records. Returns: DWA.Types.FetchXmlResponse
+     * Sends an asynchronous request to retrieve all records.
+     *
+     * @param {string} collection - The Name of the Entity Collection.
+     * @param {Array} [select] - Use the $select system query option to limit the properties returned.
+     * @param {string} [filter] - Use the $filter system query option to set criteria for which entities will be returned.
+     * @returns {Promise}
+     */
+    this.retrieveAll = function (collection, select, filter) {
+        return _retrieveAllRequest({
+            collection: collection,
+            select: select,
+            filter: filter
+        });
+    }
+
+    /**
+     * Sends an asynchronous request to execute FetchXml to retrieve records. Returns: DWA.Types.FetchXmlResponse
      *
      * @param {string} collection - An object that represents all possible options for a current request.
      * @param {string} fetchXml - FetchXML is a proprietary query language that provides capabilities to perform aggregation.
@@ -670,14 +686,12 @@ function DynamicsWebApi(config) {
      * @param {string} [impersonateUserId] - A String representing the GUID value for the Dynamics 365 system user id. Impersonates the user.
      * @returns {Promise}
      */
-    this.executeFetchXml = function (collection, fetchXml, includeAnnotations, pageNumber, pagingCookie, impersonateUserId) {
+    var executeFetchXml = function (collection, fetchXml, includeAnnotations, pageNumber, pagingCookie, impersonateUserId) {
 
         ErrorHelper.stringParameterCheck(collection, "DynamicsWebApi.executeFetchXml", "type");
         ErrorHelper.stringParameterCheck(fetchXml, "DynamicsWebApi.executeFetchXml", "fetchXml");
 
-        if (pageNumber == null) {
-            pageNumber = 1;
-        }
+        pageNumber = pageNumber || 1;
 
         ErrorHelper.numberParameterCheck(pageNumber, "DynamicsWebApi.executeFetchXml", "pageNumber");
         var replacementString = '$1 page="' + pageNumber + '"';
@@ -723,6 +737,46 @@ function DynamicsWebApi(config) {
             });
     }
 
+    /**
+     * Sends an asynchronous request to execute FetchXml to retrieve records. Returns: DWA.Types.FetchXmlResponse
+     *
+     * @param {string} collection - An object that represents all possible options for a current request.
+     * @param {string} fetchXml - FetchXML is a proprietary query language that provides capabilities to perform aggregation.
+     * @param {string} [includeAnnotations] - Use this parameter to include annotations to a result. For example: * or Microsoft.Dynamics.CRM.fetchxmlpagingcookie
+     * @param {number} [pageNumber] - Page number.
+     * @param {string} [pagingCookie] - Paging cookie. For retrieving the first page, pagingCookie should be null.
+     * @param {string} [impersonateUserId] - A String representing the GUID value for the Dynamics 365 system user id. Impersonates the user.
+     * @returns {Promise}
+     */
+    this.fetch = this.executeFetchXml = executeFetchXml;
+
+    var _executeFetchXmlAll = function (collection, fetchXml, includeAnnotations, pageNumber, pagingCookie, impersonateUserId, records) {
+        var records = records || [];
+
+        return executeFetchXml(collection, fetchXml, includeAnnotations, pageNumber, pagingCookie, impersonateUserId, records).then(function (response) {
+            records = records.concat(response.value);
+
+            if (response.PagingInfo) {
+                return _executeFetchXmlAll(collection, fetchXml, includeAnnotations, response.PagingInfo.nextPage, response.PagingInfo.cookie, impersonateUserId, records);
+            }
+
+            return { value: records };
+        });
+    }
+
+    /**
+     * Sends an asynchronous request to execute FetchXml to retrieve all records.
+     *
+     * @param {string} collection - An object that represents all possible options for a current request.
+     * @param {string} fetchXml - FetchXML is a proprietary query language that provides capabilities to perform aggregation.
+     * @param {string} [includeAnnotations] - Use this parameter to include annotations to a result. For example: * or Microsoft.Dynamics.CRM.fetchxmlpagingcookie
+     * @param {string} [impersonateUserId] - A String representing the GUID value for the Dynamics 365 system user id. Impersonates the user.
+     * @returns {Promise}
+     */
+    this.fetchAll = this.executeFetchXmlAll = function (collection, fetchXml, includeAnnotations, impersonateUserId) {
+        return _executeFetchXmlAll(collection, fetchXml, includeAnnotations, null, null, impersonateUserId);
+    }
+
     /**
      * Associate for a collection-valued navigation property. (1:N or N:N)
      *