add: use Content-ID to reference requests in a Change Set

Author: AleksandrRogov

README.md

@@ -229,19 +229,20 @@ Property Name | Type | Operation(s) Supported | Description
 ------------ | ------------- | ------------- | -------------
 async | Boolean | All | **Important! XHR requests only!** Indicates whether the requests should be made synchronously or asynchronously. Default value is `true` (asynchronously).
 collection | String | All | The name of the Entity Collection (or Entity Logical name in `v1.4.0+`).
+contentId | String | `createRequest`, `updateRequest`, `upsertRequest`, `deleteRequest` | `v1.5.6+` **BATCH REQUESTS ONLY!** Sets Content-ID header or references request in a Change Set. [More Info](https://www.odata.org/documentation/odata-version-3-0/batch-processing/)
 count | Boolean | `retrieveMultipleRequest`, `retrieveAllRequest` | Boolean that sets the $count system query option with a value of true to include a count of entities that match the filter criteria up to 5000 (per page). Do not use $top with $count!
-duplicateDetection | Boolean | `createRequest`, `updateRequest`, `upsertRequest` | `v.1.3.4+` **Web API v9+ only!** Boolean that enables duplicate detection. [More info](https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/webapi/update-delete-entities-using-web-api#check-for-duplicate-records)
+duplicateDetection | Boolean | `createRequest`, `updateRequest`, `upsertRequest` | `v.1.3.4+` **Web API v9+ only!** Boolean that enables duplicate detection. [More Info](https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/webapi/update-delete-entities-using-web-api#check-for-duplicate-records)
 entity | Object | `createRequest`, `updateRequest`, `upsertRequest` | A JavaScript object with properties corresponding to the logical name of entity attributes (exceptions are lookups and single-valued navigation properties).
 expand | Array | `retrieveRequest`, `createRequest`, `updateRequest`, `upsertRequest` | An array of Expand Objects (described below the table) representing the $expand OData System Query Option value to control which related records are also returned.
 filter | String | `retrieveRequest`, `retrieveMultipleRequest`, `retrieveAllRequest` | Use the $filter system query option to set criteria for which entities will be returned.
 id | String | `retrieveRequest`, `createRequest`, `updateRequest`, `upsertRequest`, `deleteRequest` | `deprecated in v.1.3.4` Use `key` field, instead of `id`. A String representing the Primary Key (GUID) of the record. 
-ifmatch | String | `retrieveRequest`, `updateRequest`, `upsertRequest`, `deleteRequest` | Sets If-Match header value that enables to use conditional retrieval or optimistic concurrency in applicable requests. [More info](https://msdn.microsoft.com/en-us/library/mt607711.aspx)
-ifnonematch | String | `retrieveRequest`, `upsertRequest` | Sets If-None-Match header value that enables to use conditional retrieval in applicable requests. [More info](https://msdn.microsoft.com/en-us/library/mt607711.aspx).
+ifmatch | String | `retrieveRequest`, `updateRequest`, `upsertRequest`, `deleteRequest` | Sets If-Match header value that enables to use conditional retrieval or optimistic concurrency in applicable requests. [More Info](https://msdn.microsoft.com/en-us/library/mt607711.aspx)
+ifnonematch | String | `retrieveRequest`, `upsertRequest` | Sets If-None-Match header value that enables to use conditional retrieval in applicable requests. [More Info](https://msdn.microsoft.com/en-us/library/mt607711.aspx).
 impersonate | String | All | A String representing the GUID value for the Dynamics 365 system user id. Impersonates the user.
 includeAnnotations | String | `retrieveRequest`, `retrieveMultipleRequest`, `retrieveAllRequest`, `createRequest`, `updateRequest`, `upsertRequest` | Sets Prefer header with value "odata.include-annotations=" and the specified annotation. Annotations provide additional information about lookups, options sets and other complex attribute types.
 key | String | `retrieveRequest`, `createRequest`, `updateRequest`, `upsertRequest`, `deleteRequest` | `v.1.3.4+` A String representing collection record's Primary Key (GUID) or Alternate Key(s).
 maxPageSize | Number | `retrieveMultipleRequest`, `retrieveAllRequest` | Sets the odata.maxpagesize preference value to request the number of entities returned in the response.
-mergeLabels | Boolean | `updateRequest` | `v.1.4.2+` **Metadata Update only!** Sets `MSCRM.MergeLabels` header that controls whether to overwrite the existing labels or merge your new label with any existing language labels. Default value is `false`. [More info](https://msdn.microsoft.com/en-us/library/mt593078.aspx#bkmk_updateEntities)
+mergeLabels | Boolean | `updateRequest` | `v.1.4.2+` **Metadata Update only!** Sets `MSCRM.MergeLabels` header that controls whether to overwrite the existing labels or merge your new label with any existing language labels. Default value is `false`. [More Info](https://msdn.microsoft.com/en-us/library/mt593078.aspx#bkmk_updateEntities)
 metadataAttributeType | String | `retrieveRequest`, `updateRequest` | `v.1.4.3+` Casts the Attributes to a specific type. (Used in requests to Attribute Metadata) [More Info](https://msdn.microsoft.com/en-us/library/mt607522.aspx#Anchor_4)
 navigationProperty | String | `retrieveRequest`, `createRequest`, `updateRequest` | A String representing the name of a single-valued navigation property. Useful when needed to retrieve information about a related record in a single request.
 navigationPropertyKey | String | `retrieveRequest`, `createRequest`, `updateRequest` | `v.1.4.3+` A String representing navigation property's Primary Key (GUID) or Alternate Key(s). (For example, to retrieve Attribute Metadata)
@@ -1024,11 +1025,41 @@ dynamicsWebApi.executeBatch().then(function (responses) {
 just pass `null` if you need to add additional parameters in the request, 
 for example: `dynamicsWebApi.deleteRecord('00000000-0000-0000-0000-000000000001', 'contacts', null, null, 'firstname')`.
 
+## Use Content-ID to reference requests in a Change Set
+
+Starting from v.1.5.6 you can reference a request from a Change Set. For example, if you want to create related entities in a single batch request:
+
+```js
+var order = {
+    name: '1 year membership'
+};
+
+var contact = {
+    firstname: "test content",
+    lastname: "id"
+};
+
+dynamicsWebApi.startBatch();
+dynamicsWebApi.createRequest({ entity: order, collection: 'salesorders', contentId: '1' });
+dynamicsWebApi.createRequest({ entity: contact, collection: 'customerid_contact', contentId: "$1" });
+
+dynamicsWebApi.executeBatch()
+    .then(function (responses) {
+        var salesorderId = responses[0];
+        //responses[1]; is undefined <- CRM Web API limitation
+    }).catch(function (error) {
+        //catch error here
+    });
+
+```
+
+Note that the second response does not have a returned value, it is a CRM Web API limitation.
+**Important!** DynamicsWebApi automatically assigns value to a `Content-ID` if it is not provided, therefore, please set your `Content-ID` value less than 100000.
+
 #### Limitations
 
 Currently, there are some limitations in DynamicsWebApi Batch Operations:
 
-* `Content-ID` header cannot be used to reference the Uri of any entity created in a single operation. **This is an upcoming feature**.
 * Operations that use pagination to recursively retrieve all records cannot be used in a 'batch mode'. These include: `retrieveAll`, `retrieveAllRequest`, `countAll`, `fetchAll`, `executeFetchXmlAll`.
 You will get an error saying that the operation is incompatible with a 'batch mode'.
 * The following limitation is for external applications (working outside D365 CE forms). `useEntityNames` may not work in a 'batch mode' if it is set to `true`. 
@@ -1913,8 +1944,8 @@ the config option "formatted" will enable developers to retrieve all information
 - [X] Entity Relationships and Global Option Sets helpers. `Implemented in v.1.4.6`
 - [X] Batch requests. `Implemented in v.1.5.0`
 - [X] TypeScript declaration files `d.ts` `Added in v.1.5.3`.
+- [X] Implement `Content-ID` header to reference a request in a Change Set in a batch operation `Added in v.1.5.6`.
 - [ ] Upload DynamicsWebApi declaration files to DefinitelyTyped repository.
-- [ ] Implement `Content-ID` header to reference a created entity in a batch operation.
 
 Many more features to come!
 

lib/dynamics-web-api-callbacks.js

@@ -85,6 +85,7 @@ var dwaRequest = function () {
  * @property {string} userQuery - A String representing the GUID value of the user query.
  * @property {boolean} mergeLabels - If set to 'true', DynamicsWebApi adds a request header 'MSCRM.MergeLabels: true'. Default value is 'false'
  * @property {boolean} isBatch - If set to 'true', DynamicsWebApi treats a request as a part of a batch request. Call ExecuteBatch to execute all requests in a batch. Default value is 'false'.
+ * @property {string} contentId - BATCH REQUESTS ONLY! Sets Content-ID header or references request in a Change Set.
  */
 
 /**

lib/dynamics-web-api.js

@@ -88,6 +88,7 @@ var dwaRequest = function () {
  * @property {string} userQuery - A String representing the GUID value of the user query.
  * @property {boolean} mergeLabels - If set to 'true', DynamicsWebApi adds a request header 'MSCRM.MergeLabels: true'. Default value is 'false'.
  * @property {boolean} isBatch - If set to 'true', DynamicsWebApi treats a request as a part of a batch request. Call ExecuteBatch to execute all requests in a batch. Default value is 'false'.
+ * @property {string} contentId - BATCH REQUESTS ONLY! Sets Content-ID header or references request in a Change Set.
  */
 
 /**

lib/requests/http.js

@@ -105,8 +105,8 @@ var httpRequest = function (options) {
                     }
                     var error = new Error();
                     Object.keys(crmError).forEach(k => {
-                      error[k] = crmError[k];
-                    })
+                        error[k] = crmError[k];
+                    });
                     error.status = res.statusCode;
                     error.statusText = request.statusText;
                     errorCallback(error);
@@ -123,14 +123,7 @@ var httpRequest = function (options) {
         });
     }
 
-    //request.on('timeout', function () {
-    //  request.abort();
-    //});
-
     request.on('error', function (error) {
-        //if (request.aborted) {
-        //  error = new Error('Request timed out: ' + error);
-        //}
         responseParams.length = 0;
         errorCallback(error);
     });

lib/utilities/BatchConverter.js

@@ -10,7 +10,7 @@ var convertToBatch = function (requests) {
 
     var batchBody = [];
     var currentChangeSet = null;
-    var contentId = 0;
+    var contentId = 100000;
 
     for (var i = 0; i < requests.length; i++) {
         var request = requests[i];
@@ -21,7 +21,7 @@ var convertToBatch = function (requests) {
             batchBody.push('\n--' + currentChangeSet + '--');
 
             currentChangeSet = null;
-            contentId = 0;
+            contentId = 100000;
         }
 
         if (!currentChangeSet) {
@@ -41,10 +41,19 @@ var convertToBatch = function (requests) {
         batchBody.push('Content-Transfer-Encoding: binary');
 
         if (!isGet) {
-            batchBody.push('Content-ID: ' + ++contentId);
+            var contentIdValue = request.headers.hasOwnProperty('Content-ID')
+                ? request.headers['Content-ID']
+                : ++contentId;
+
+            batchBody.push('Content-ID: ' + contentIdValue);
         }
 
-        batchBody.push('\n' + request.method + ' ' + request.config.webApiUrl + request.path + ' HTTP/1.1');
+        if (!request.path.startsWith("$")) {
+            batchBody.push('\n' + request.method + ' ' + request.config.webApiUrl + request.path + ' HTTP/1.1');
+        }
+        else {
+            batchBody.push('\n' + request.method + ' ' + request.path + ' HTTP/1.1');
+        }
 
         if (isGet) {
             batchBody.push('Accept: application/json');
@@ -54,7 +63,7 @@ var convertToBatch = function (requests) {
         }
 
         for (var key in request.headers) {
-            if (key === 'Authorization')
+            if (key === 'Authorization' || key === 'Content-ID')
                 continue;
 
             batchBody.push(key + ': ' + request.headers[key]);

lib/utilities/RequestConverter.js

@@ -166,6 +166,13 @@ function convertRequestOptions(request, functionName, url, joinSymbol, config) {
             headers['MSCRM.MergeLabels'] = 'true';
         }
 
+        if (request.contentId) {
+            ErrorHelper.stringParameterCheck(request.contentId, 'DynamicsWebApi.' + functionName, 'request.contentId');
+            if (!request.contentId.startsWith('$')) {
+                headers['Content-ID'] = request.contentId;
+            }
+        }
+
         if (request.isBatch) {
             ErrorHelper.boolParameterCheck(request.isBatch, 'DynamicsWebApi.' + functionName, 'request.isBatch');
         }
@@ -216,6 +223,13 @@ function convertRequest(request, functionName, config) {
             ErrorHelper.stringParameterCheck(request.collection, 'DynamicsWebApi.' + functionName, "request.collection");
             url = request.collection;
 
+            if (request.contentId) {
+                ErrorHelper.stringParameterCheck(request.contentId, 'DynamicsWebApi.' + functionName, 'request.contentId');
+                if (request.contentId.startsWith('$')) {
+                    url = request.contentId + '/' + url;
+                }
+            }
+
             //add alternate key feature
             if (request.key) {
                 request.key = ErrorHelper.keyParameterCheck(request.key, 'DynamicsWebApi.' + functionName, "request.key");

tests/main-tests.js

@@ -4731,6 +4731,60 @@ describe("promises -", function () {
                 expect(scope.isDone()).to.be.true;
             });
         });
+
+        describe("create / create with Content-ID", function () {
+            var scope;
+            var rBody = mocks.data.batchCreateContentID;
+            var rBodys = rBody.split('\n');
+            var checkBody = '';
+            for (var i = 0; i < rBodys.length; i++) {
+                checkBody += rBodys[i];
+            }
+            before(function () {
+                var response = mocks.responses.batchUpdateDelete;
+                scope = nock(mocks.webApiUrl + '$batch')
+                    .filteringRequestBody(function (body) {
+                        body = body.replace(/dwa_batch_[\d\w]{8}-[\d\w]{4}-[\d\w]{4}-[\d\w]{4}-[\d\w]{12}/g, 'dwa_batch_XXX');
+                        body = body.replace(/changeset_[\d\w]{8}-[\d\w]{4}-[\d\w]{4}-[\d\w]{4}-[\d\w]{12}/g, 'changeset_XXX');
+                        var bodys = body.split('\n');
+
+                        var resultBody = '';
+                        for (var i = 0; i < bodys.length; i++) {
+                            resultBody += bodys[i];
+                        }
+                        return resultBody;
+                    })
+                    .post("", checkBody)
+                    .reply(response.status, response.responseText, response.responseHeaders);
+            });
+
+            after(function () {
+                nock.cleanAll();
+            });
+
+            it("returns a correct response", function (done) {
+                dynamicsWebApiTest.startBatch();
+
+                dynamicsWebApiTest.createRequest({ collection: 'records', entity: { firstname: "Test", lastname: "Batch!" }, contentId: '1' });
+                dynamicsWebApiTest.createRequest({ collection: 'test_property', entity: { firstname: "Test1", lastname: "Batch!" }, contentId: '$1' });
+
+                dynamicsWebApiTest.executeBatch()
+                    .then(function (object) {
+                        expect(object.length).to.be.eq(2);
+
+                        expect(object[0]).to.be.eq(mocks.data.testEntityId);
+                        expect(object[1]).to.be.undefined;
+
+                        done();
+                    }).catch(function (object) {
+                        done(object);
+                    });
+            });
+
+            it("all requests have been made", function () {
+                expect(scope.isDone()).to.be.true;
+            });
+        });
     });
 
     describe("dynamicsWebApi.constructor -", function () {