Skip to content

Commit 77b1866

Browse files
AleksandrRogovAleksandrRogov
committed
added: deprecation warnings #136 
1 parent 367cb23 commit 77b1866

File tree

7 files changed

+285
-22
lines changed

7 files changed

+285
-22
lines changed

‎README.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -236,18 +236,28 @@ proxy | Object | `v.1.7.2+` Proxy configuration object. [More Info](#using-proxy
236236
returnRepresentation | Boolean | Defaults Prefer header with value "return=representation". Use this property to return just created or updated entity in a single request.
237237
timeout | Number | Sets a number of milliseconds before a request times out.
238238
useEntityNames | Boolean | `v.1.4.0+` Indicates whether to use entity logical names instead of collection logical names during requests.
239-
webApiUrl | String | A complete URL string to Web API. Example of the URL: "https://myorg.api.crm.dynamics.com/api/data/v9.1/". If it is specified then webApiVersion property will not be used even if it is not empty.
240-
webApiVersion | String | Version of the Web API. Default version is "8.0".
239+
webApiUrl | String | **Deprecated!** Use `serverUrl` together with `dataApi` instead. A complete URL string to Web API. Example of the URL: "https://myorg.api.crm.dynamics.com/api/data/v9.1/". If it is specified then webApiVersion property will not be used even if it is not empty.
240+
webApiVersion | String | **Deprecated!** Use `dataApi.version` instead. Version of the Web API. Default version is "8.0".
241+
dataApi | Object | `v1.7.8+` Configuration object for Dataverse Web API.
242+
serverUrl | String | `v1.7.8+` The url to Dataverse API server, for example: https://contoso.api.crm.dynamics.com/. It is required when used in Node.js application.
241243

242244
Configuration property `webApiVersion` is required only when DynamicsWebApi used inside CRM.
243245
Property `webApiUrl` is required when DynamicsWebApi used externally.
244246

247+
**Important!** `webApiUrl` and `webApiVersion` are deprecated and will be removed in v2. Please use `serverUrl` and `dataApi` instead.
248+
245249
**Important!** If both configuration properties set then `webApiUrl` will have a higher priority than `webApiVersion`, so the last one will be skipped.
246250

247251
**Important!** Please note, if you are using `DynamicsWebApi` **outside Microsoft Dynamics 365** and set `useEntityNames` to `true` **the first request** to Web Api
248252
will fetch `LogicalCollectionName` and `LogicalName` from entity metadata for all entities. It does not happen when `DynamicsWebApi`
249253
is used in Microsoft Dynamics 365 Web Resources (there is no additional request, no impact on perfomance).
250254

255+
**dataApi** properties:
256+
| Property Name | Type | Description |
257+
|--------|--------|--------|
258+
| path | `String` | Optional. A path to API, for example: "data". |
259+
| version | `String` | Optional. API Version, for example: "9.1" or "9.2". |
260+
251261
## Request Examples
252262

253263
DynamicsWebApi supports __Basic__ and __Advanced__ calls to Web API.
@@ -274,9 +284,9 @@ bypassCustomPluginExecution | Boolean | `createRequest`, `updateRequest`, `upser
274284
collection | String | All | The name of the Entity Collection (or Entity Logical name in `v1.4.0+`).
275285
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/)
276286
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!
277-
data | ArrayBuffer / Buffer (for node.js) | `uploadFile` | `v.1.7.0+` **Web API v9.1+ only!** File buffer for uploading to File Attributes.
287+
data | Object / ArrayBuffer / Buffer (for node.js) | `uploadFile` and `v.1.7.8+` for `createRequest`, `updateRequest`, `upsertRequest` | `v.1.7.0+` **Web API v9.1+ only!** File buffer for uploading to File Attributes. `v.1.7.8+` A JavaScript object with properties corresponding to the logical name of entity attributes (exceptions are lookups and single-valued navigation properties).
278288
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)
279-
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).
289+
entity | Object | `createRequest`, `updateRequest`, `upsertRequest` | **Deprecated!** Use `data` instead. A JavaScript object with properties corresponding to the logical name of entity attributes (exceptions are lookups and single-valued navigation properties).
280290
expand | Array | `retrieveRequest`, `retrieveMultipleRequest`, `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.
281291
fieldName | String | `uploadFile`, `downloadFile`, `deleteRequest` | `v.1.7.0+` **Web API v9.1+ only!** Use this option to specify the name of the file attribute in Dynamics 365. [More Info](https://docs.microsoft.com/en-us/powerapps/developer/common-data-service/file-attributes)
282292
fileName | String | `uploadFile` | `v.1.7.0+` **Web API v9.1+ only!** Specifies the name of the file

‎lib/dynamics-web-api-callbacks.js‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,8 @@ if (!String.prototype.endsWith || !String.prototype.startsWith) {
5656

5757
/**
5858
* Constructor.
59+
* @deprecated Please use DynamicsWebApi with Promises. Callbacks will be fully removed in v2.
60+
*
5961
* @constructor
6062
* @param {DWAConfig} [config] - configuration object
6163
* @example
@@ -79,6 +81,8 @@ function DynamicsWebApi(config) {
7981
maxPageSize: null,
8082
returnRepresentation: null,
8183
proxy: null,
84+
serverUrl: null,
85+
path: "data",
8286
};
8387

8488
var _isBatch = false;
@@ -98,6 +102,27 @@ function DynamicsWebApi(config) {
98102
this.setConfig = function (config) {
99103
var isVersionDiffer = (config.webApiVersion || _internalConfig.webApiVersion) !== _internalConfig.webApiVersion;
100104

105+
if (config.serverUrl) {
106+
ErrorHelper.stringParameterCheck(config.serverUrl, "DynamicsWebApi.setConfig", "config.serverUrl");
107+
_internalConfig.serverUrl = config.serverUrl.endsWith("/") ? config.serverUrl.slice(0, -1) : config.serverUrl;
108+
}
109+
110+
if (config.dataApi) {
111+
if (config.dataApi.version) {
112+
ErrorHelper.stringParameterCheck(config.webApiVersion, "DynamicsWebApi.setConfig", "config.dataApi.version");
113+
_internalConfig.webApiVersion = config.dataApi.version;
114+
}
115+
116+
if (config.dataApi.path) {
117+
ErrorHelper.stringParameterCheck(config.dataApi.path, "DynamicsWebApi.setConfig", "config.dataApi.path");
118+
_internalConfig.path = config.dataApi.path.replace("/", "");
119+
}
120+
121+
_internalConfig.webApiUrl = _internalConfig.serverUrl
122+
? `${_internalConfig.serverUrl}/api/${_internalConfig.path}/v${_internalConfig.webApiVersion}/`
123+
: Utility.initWebApiUrl(_internalConfig.webApiVersion);
124+
}
125+
101126
if (config.webApiVersion) {
102127
ErrorHelper.stringParameterCheck(config.webApiVersion, "DynamicsWebApi.setConfig", "config.webApiVersion");
103128
_internalConfig.webApiVersion = config.webApiVersion;

‎lib/dynamics-web-api.js‎

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,16 @@ if (!String.prototype.endsWith || !String.prototype.startsWith) {
1010
require("./polyfills/string-es6");
1111
}
1212

13+
/**
14+
* @typedef {object} APIConfig
15+
* @property {string} path
16+
* @property {string} version
17+
*/
18+
1319
/**
1420
* Configuration object for DynamicsWebApi
1521
* @typedef {object} DWAConfig
16-
* @property {string} webApiUrl - A String representing the GUID value for the Dynamics 365 system user id. Impersonates the user.
22+
* @property {string} webApiUrl - A String representing the GUID value for the Dynamics 365 system user id. Impersonates the user. @deprecated use serverUrl with dataApi
1723
* @property {string} impersonate - A String representing a GUID value for the Dynamics 365 system user id.
1824
* @property {string} impersonate - A String representing a URL to Web API (webApiVersion not required if webApiUrl specified) [not used inside of CRM]
1925
* @property {string} impersonateAAD - A String representing a GUID value for the Azure active directory object id.
@@ -22,6 +28,7 @@ if (!String.prototype.endsWith || !String.prototype.startsWith) {
2228
* @property {string} maxPageSize - Sets the odata.maxpagesize preference value to request the number of entities returned in the response.
2329
* @property {boolean} returnRepresentation - Sets Prefer header request with value "return=representation". Use this property to return just created or updated entity in a single request.
2430
* @property {boolean} useEntityNames - Indicates whether to use Entity Logical Names instead of Collection Logical Names.
31+
* @property {APIConfig} dataApi
2532
*/
2633

2734
/**
@@ -42,7 +49,8 @@ if (!String.prototype.endsWith || !String.prototype.startsWith) {
4249
* @property {string} ifmatch - Sets If-Match header value that enables to use conditional retrieval or optimistic concurrency in applicable requests.
4350
* @property {string} ifnonematch - Sets If-None-Match header value that enables to use conditional retrieval in applicable requests.
4451
* @property {boolean} returnRepresentation - Sets Prefer header request with value "return=representation". Use this property to return just created or updated entity in a single request.
45-
* @property {Object} entity - A JavaScript object with properties corresponding to the logical name of entity attributes (exceptions are lookups and single-valued navigation properties).
52+
* @property {Object} data - A JavaScript object with properties corresponding to the logical name of entity attributes (exceptions are lookups and single-valued navigation properties).
53+
* @property {Object} entity - A JavaScript object with properties corresponding to the logical name of entity attributes (exceptions are lookups and single-valued navigation properties). @deprecated use entity
4654
* @property {string} impersonate - Impersonates the user. A String representing the GUID value for the Dynamics 365 system user id.
4755
* @property {string} impersonateAAD - Impersonates the user. A String representing the GUID value for the Azure active directory object id.
4856
* @property {string} navigationProperty - 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.
@@ -68,7 +76,10 @@ if (!String.prototype.endsWith || !String.prototype.startsWith) {
6876
*var dynamicsWebApi = new DynamicsWebApi({ webApiVersion: '9.0' });
6977
* @example
7078
*var dynamicsWebApi = new DynamicsWebApi({
71-
* webApiUrl: 'https:/myorg.api.crm.dynamics.com/api/data/v9.0/',
79+
* serverUrl: 'https:/myorg.api.crm.dynamics.com/',
80+
* dataApi: {
81+
* version: '9.0'
82+
* }
7283
* includeAnnotations: 'OData.Community.Display.V1.FormattedValue'
7384
*});
7485
*/
@@ -83,6 +94,8 @@ function DynamicsWebApi(config) {
8394
maxPageSize: null,
8495
returnRepresentation: null,
8596
proxy: null,
97+
serverUrl: null,
98+
path: "data",
8699
};
87100

88101
var _isBatch = false;
@@ -102,6 +115,27 @@ function DynamicsWebApi(config) {
102115
this.setConfig = function (config) {
103116
var isVersionDiffer = (config.webApiVersion || _internalConfig.webApiVersion) !== _internalConfig.webApiVersion;
104117

118+
if (config.serverUrl) {
119+
ErrorHelper.stringParameterCheck(config.serverUrl, "DynamicsWebApi.setConfig", "config.serverUrl");
120+
_internalConfig.serverUrl = config.serverUrl.endsWith("/") ? config.serverUrl.slice(0, -1) : config.serverUrl;
121+
}
122+
123+
if (config.dataApi) {
124+
if (config.dataApi.version) {
125+
ErrorHelper.stringParameterCheck(config.dataApi.version, "DynamicsWebApi.setConfig", "config.dataApi.version");
126+
_internalConfig.webApiVersion = config.dataApi.version;
127+
}
128+
129+
if (config.dataApi.path) {
130+
ErrorHelper.stringParameterCheck(config.dataApi.path, "DynamicsWebApi.setConfig", "config.dataApi.path");
131+
_internalConfig.path = config.dataApi.path.replace("/", "");
132+
}
133+
134+
_internalConfig.webApiUrl = _internalConfig.serverUrl
135+
? `${_internalConfig.serverUrl}/api/${_internalConfig.path}/v${_internalConfig.webApiVersion}/`
136+
: Utility.initWebApiUrl(_internalConfig.webApiVersion);
137+
}
138+
105139
if (config.webApiVersion) {
106140
ErrorHelper.stringParameterCheck(config.webApiVersion, "DynamicsWebApi.setConfig", "config.webApiVersion");
107141
_internalConfig.webApiVersion = config.webApiVersion;

‎tests/main-tests.js‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1889,6 +1889,46 @@ describe("promises -", function () {
18891889
});
18901890
});
18911891

1892+
describe("basic - using request.data instead of request.entity", function () {
1893+
var scope;
1894+
before(function () {
1895+
var response = mocks.responses.basicEmptyResponseSuccess;
1896+
scope = nock(mocks.webApiUrl, {
1897+
reqheaders: {
1898+
"If-Match": "*",
1899+
},
1900+
})
1901+
.patch(mocks.responses.testEntityUrl, mocks.data.testEntity)
1902+
.reply(response.status, response.responseText, response.responseHeaders);
1903+
});
1904+
1905+
after(function () {
1906+
nock.cleanAll();
1907+
});
1908+
1909+
it("returns a correct response", function (done) {
1910+
var dwaRequest = {
1911+
id: mocks.data.testEntityId,
1912+
collection: "tests",
1913+
data: mocks.data.testEntity,
1914+
};
1915+
1916+
dynamicsWebApiTest
1917+
.updateRequest(dwaRequest)
1918+
.then(function (object) {
1919+
expect(object).to.be.true;
1920+
done();
1921+
})
1922+
.catch(function (object) {
1923+
done(object);
1924+
});
1925+
});
1926+
1927+
it("all requests have been made", function () {
1928+
expect(scope.isDone()).to.be.true;
1929+
});
1930+
});
1931+
18921932
describe("return representation", function () {
18931933
var scope;
18941934
before(function () {
@@ -5907,6 +5947,49 @@ describe("promises -", function () {
59075947
});
59085948
});
59095949

5950+
describe("authorization - dataApi", function () {
5951+
var scope;
5952+
before(function () {
5953+
var response = mocks.responses.multipleResponse;
5954+
scope = nock(mocks.webApiUrl, {
5955+
reqheaders: {
5956+
Authorization: "Bearer token001",
5957+
},
5958+
})
5959+
.get("/tests")
5960+
.reply(response.status, response.responseText, response.responseHeaders);
5961+
});
5962+
5963+
after(function () {
5964+
nock.cleanAll();
5965+
});
5966+
5967+
it("sends the request to the right end point and returns a response", function (done) {
5968+
var getToken = function (callback) {
5969+
var adalCallback = function (token) {
5970+
callback(token);
5971+
};
5972+
5973+
adalCallback({ accessToken: "token001" });
5974+
};
5975+
5976+
var dynamicsWebApiAuth = new DynamicsWebApi({ onTokenRefresh: getToken, serverUrl: mocks.serverUrl, dataApi: { version: "8.2" } });
5977+
dynamicsWebApiAuth
5978+
.retrieveMultipleRequest({ collection: "tests" })
5979+
.then(function (object) {
5980+
expect(object).to.deep.equal(mocks.responses.multiple());
5981+
done();
5982+
})
5983+
.catch(function (object) {
5984+
done(object);
5985+
});
5986+
});
5987+
5988+
it("all requests have been made", function () {
5989+
expect(scope.isDone()).to.be.true;
5990+
});
5991+
});
5992+
59105993
describe("authorization - plain token", function () {
59115994
var scope;
59125995
before(function () {
@@ -6560,6 +6643,43 @@ describe("promises -", function () {
65606643
expect(scope.isDone()).to.be.true;
65616644
});
65626645
});
6646+
6647+
describe("dataApi is overriden by the new config set", function () {
6648+
var dynamicsWebApi81 = new DynamicsWebApi({ dataApi: { version: "8.1" } });
6649+
6650+
var scope;
6651+
before(function () {
6652+
var response = mocks.responses.multipleResponse;
6653+
scope = nock(mocks.webApiUrl, {
6654+
reqheaders: {
6655+
MSCRMCallerID: mocks.data.testEntityId2,
6656+
},
6657+
})
6658+
.get("/tests")
6659+
.reply(response.status, response.responseText, response.responseHeaders);
6660+
});
6661+
6662+
after(function () {
6663+
nock.cleanAll();
6664+
});
6665+
6666+
it("sends the request to the right end point and returns a response", function (done) {
6667+
dynamicsWebApi81.setConfig({ dataApi: { version: "8.2" }, impersonate: mocks.data.testEntityId2 });
6668+
dynamicsWebApi81
6669+
.retrieveMultipleRequest({ collection: "tests" })
6670+
.then(function (object) {
6671+
expect(object).to.deep.equal(mocks.responses.multiple());
6672+
done();
6673+
})
6674+
.catch(function (object) {
6675+
done(object);
6676+
});
6677+
});
6678+
6679+
it("all requests have been made", function () {
6680+
expect(scope.isDone()).to.be.true;
6681+
});
6682+
});
65636683
});
65646684

65656685
describe("dynamicsWebApi.initializeInstance -", function () {
@@ -6632,6 +6752,38 @@ describe("promises -", function () {
66326752
expect(scope.isDone()).to.be.true;
66336753
});
66346754
});
6755+
6756+
describe("dataApi test", function () {
6757+
var dynamicsWebApi81 = new DynamicsWebApi();
6758+
dynamicsWebApi81.setConfig({ dataApi: { version: "8.1" }, impersonate: mocks.data.testEntityId2 });
6759+
6760+
var scope;
6761+
before(function () {
6762+
var response = mocks.responses.multipleResponse;
6763+
scope = nock(mocks.webApiUrl).get(mocks.responses.collectionUrl).reply(response.status, response.responseText, response.responseHeaders);
6764+
});
6765+
6766+
after(function () {
6767+
nock.cleanAll();
6768+
});
6769+
6770+
it("sends the request to the right end point", function (done) {
6771+
var dynamicsWebApiCopy = dynamicsWebApi81.initializeInstance({ dataApi: { version: "8.2" } });
6772+
dynamicsWebApiCopy
6773+
.retrieveMultipleRequest({ collection: "tests" })
6774+
.then(function (object) {
6775+
expect(object).to.deep.equal(mocks.responses.multiple());
6776+
done();
6777+
})
6778+
.catch(function (object) {
6779+
done(object);
6780+
});
6781+
});
6782+
6783+
it("all requests have been made", function () {
6784+
expect(scope.isDone()).to.be.true;
6785+
});
6786+
});
66356787
});
66366788

66376789
describe("dynamicsWebApi proxy -", function () {

‎tests/stubs.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ global.Xrm = {
1212

1313
var DWA = require("../lib/dwa");
1414
var webApiUrl = "http://testorg.crm.dynamics.com/api/data/v8.2/";
15+
var serverUrl = "http://testorg.crm.dynamics.com/";
1516
var webApiUrl90 = "http://testorg.crm.dynamics.com/api/data/v9.0/";
1617
var webApiUrl81 = "http://testorg.crm.dynamics.com/api/data/v8.1/";
1718
var webApiUrl80 = "http://testorg.crm.dynamics.com/api/data/v8.0/";
@@ -1190,5 +1191,6 @@ module.exports = {
11901191
webApiUrl90: webApiUrl90,
11911192
webApiUrl81: webApiUrl81,
11921193
webApiUrl80: webApiUrl80,
1194+
serverUrl: serverUrl,
11931195
utils: utils,
11941196
};

0 commit comments

Comments
 (0)