Simplified access to formatted and lookup data values

Author: AleksandrRogov

DynamicsWebApi.njsproj

@@ -8,6 +8,9 @@
     <EnableTypeScript>true</EnableTypeScript>
     <TypeScriptSourceMap>true</TypeScriptSourceMap>
     <TypeScriptModuleKind>CommonJS</TypeScriptModuleKind>
+    <TypeScriptToolsVersion>2.3</TypeScriptToolsVersion>
+    <NodeExePath>
+    </NodeExePath>
   </PropertyGroup>
   <Import Project="$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props" Condition="Exists('$(MSBuildExtensionsPath)\$(MSBuildToolsVersion)\Microsoft.Common.props')" />
   <PropertyGroup>
@@ -23,12 +26,25 @@
     <OutputPath>.</OutputPath>
     <TargetFrameworkVersion>v4.0</TargetFrameworkVersion>
     <ProjectTypeGuids>{3AF33F2E-1136-4D97-BBB7-1795711AC8B8};{349c5851-65df-11da-9384-00065b846f21};{9092AA53-FB77-4645-B42D-1CCCA6BD08BD}</ProjectTypeGuids>
-    <ProjectView>ShowAllFiles</ProjectView>
+    <ProjectView>ProjectFiles</ProjectView>
     <NodejsPort>1337</NodejsPort>
-    <StartWebBrowser>true</StartWebBrowser>
+    <StartWebBrowser>True</StartWebBrowser>
   </PropertyGroup>
   <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
     <DebugSymbols>true</DebugSymbols>
+    <TypeScriptTarget>ES6</TypeScriptTarget>
+    <TypeScriptJSXEmit>None</TypeScriptJSXEmit>
+    <TypeScriptModuleKind>CommonJS</TypeScriptModuleKind>
+    <TypeScriptCompileOnSaveEnabled>True</TypeScriptCompileOnSaveEnabled>
+    <TypeScriptNoImplicitAny>False</TypeScriptNoImplicitAny>
+    <TypeScriptRemoveComments>False</TypeScriptRemoveComments>
+    <TypeScriptOutFile />
+    <TypeScriptOutDir />
+    <TypeScriptGeneratesDeclarations>False</TypeScriptGeneratesDeclarations>
+    <TypeScriptNoEmitOnError>True</TypeScriptNoEmitOnError>
+    <TypeScriptSourceMap>True</TypeScriptSourceMap>
+    <TypeScriptMapRoot />
+    <TypeScriptSourceRoot />
   </PropertyGroup>
   <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
     <DebugSymbols>true</DebugSymbols>

README.md

@@ -37,6 +37,7 @@ Any suggestions are welcome!
     * [Fetch All records](#fetch-all-records)
   * [Execute Web API functions](#execute-web-api-functions)
   * [Execute Web API actions](#execute-web-api-actions)
+* [Formatted Values and Lookup Properties](#formatted-values-and-lookup-properties)
 * [JavaScript Promises](#javascript-promises)
 * [JavaScript Callbacks](#javascript-callbacks)
 
@@ -862,17 +863,54 @@ dynamicsWebApi.executeUnboundAction("WinOpportunity", actionRequest).then(functi
 });
 ```
 
+## Formatted Values and Lookup Properties
+
+Starting from version 1.3.0 it became easier to access formatted values for properties and lookup data in response objects. 
+DynamicsWebApi automatically creates aliases for each property that contains a formatted value or lookup data.
+For example:
+
+```js
+//before v.1.3.0 a formatted value for account.donotpostalmail field could be accessed as following:
+var doNotPostEmailFormatted = response['[email protected]'];
+
+//starting with v.1.3.0 it can be simplified
+doNotPostEmailFormatted = response.donotpostalmail_Formatted;
+
+//same for lookup data
+//before v.1.3.0
+var customerName = response['[email protected]'];
+var customerEntityLogicalName = response['[email protected]'];
+var customerNavigationProperty = response['_customerid_value@Microsoft.Dynamics.CRM.associatednavigationproperty'];
+
+//starting with v.1.3.0
+customerName = response._customerid_value_Formatted;
+customerEntityLogicalName = response._customerid_value_LogicalName;
+customerNavigationProperty = response._customerid_value_NavigationProperty;
+```
+
+If you still want to use old properties you can do so, they are not removed from the response, so it does not break your existing functionality.
+
+As you have already noticed formatted and lookup data values are accesed by adding a particular suffix to a property name, 
+the following table summarizes it.
+
+OData Annotation | Property Suffix
+------------ | -------------
+`@OData.Community.Display.V1.FormattedValue` | `_Formatted`
+`@Microsoft.Dynamics.CRM.lookuplogicalname` | `_LogicalName`
+`@Microsoft.Dynamics.CRM.associatednavigationproperty` | `_NavigationProperty`
+
 ### In Progress
 
 - [X] Overloaded functions with rich request options for all Web API operations.
-- [X] Get all pages requests, such as: countAll, retrieveMultipleAll, fetchXmlAll and etc. Implemented in v.1.2.5.
+- [X] Get all pages requests, such as: countAll, retrieveMultipleAll, fetchXmlAll and etc. `Implemented in v.1.2.5`
 - [X] Web API requests that have long URL (more than 2000 characters) should be automatically converted to batch requests. 
-Feature is very convenient for big Fetch XMLs. Implemented in v.1.2.8.
-- [ ] Web API Authentication for On-Premise instances.
-- [ ] Intellisense for request objects.
-- [ ] "Formatted" values in responses. For instance: Web API splits information about lookup fields into separate properties, 
+Feature is very convenient for big Fetch XMLs. `Implemented in v.1.2.8`
+- [X] "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.
+- [X] Simplified names for "Formatted" properties. `Implemeted in v.1.3.0`
 - [ ] Batch requests.
+- [ ] Web API Authentication for On-Premise instances.
+- [ ] Intellisense for request objects.
 - [ ] Use entity names instead of collection names. I have not done an investigation about it but if you, by any chance, know how to do that, 
 I will be very grateful for an advice! Quick guess, does it work like in English language?
 

lib/dynamics-web-api-callbacks.js

@@ -697,16 +697,8 @@ function DynamicsWebApi(config) {
         var toCount = request.count;
 
         var onSuccess = function (response) {
-            if (response.data['@odata.nextLink'] != null) {
-                response.data.oDataNextLink = response.data['@odata.nextLink'];
-            }
             if (toCount) {
-                response.data.oDataCount = response.data['@odata.count'] != null
-                    ? parseInt(response.data['@odata.count'])
-                    : 0;
-            }
-            if (response.data['@odata.context'] != null) {
-                response.data.oDataContext = response.data['@odata.context'];
+                response.data.oDataCount = response.data.oDataCount || 0;
             }
 
             successCallback(response.data);
@@ -799,12 +791,8 @@ function DynamicsWebApi(config) {
         var encodedFetchXml = encodeURIComponent(fetchXml);
 
         var onSuccess = function (response) {
-            if (response.data['@Microsoft.Dynamics.CRM.fetchxmlpagingcookie'] != null) {
-                response.data.PagingInfo = Utility.getFetchXmlPagingCookie(response.data['@Microsoft.Dynamics.CRM.fetchxmlpagingcookie'], pageNumber);
-            }
-
-            if (response.data['@odata.context'] != null) {
-                response.data.oDataContext = response.data['@odata.context'];
+            if (response.data['@' + DWA.Prefer.Annotations.FetchXmlPagingCookie] != null) {
+                response.data.PagingInfo = Utility.getFetchXmlPagingCookie(response.data['@' + DWA.Prefer.Annotations.FetchXmlPagingCookie], pageNumber);
             }
 
             successCallback(response.data);

lib/dynamics-web-api.js

@@ -548,16 +548,9 @@ function DynamicsWebApi(config) {
 
         return _sendRequest("GET", result.url, null, result.headers)
             .then(function (response) {
-                if (response.data['@odata.nextLink'] != null) {
-                    response.data.oDataNextLink = response.data['@odata.nextLink'];
-                }
+
                 if (toCount) {
-                    response.data.oDataCount = response.data['@odata.count'] != null
-                        ? parseInt(response.data['@odata.count'])
-                        : 0;
-                }
-                if (response.data['@odata.context'] != null) {
-                    response.data.oDataContext = response.data['@odata.context'];
+                    response.data.oDataCount = response.data.oDataCount || 0;
                 }
 
                 return response.data;
@@ -725,12 +718,8 @@ function DynamicsWebApi(config) {
         return _sendRequest("GET", result.url + "?fetchXml=" + encodedFetchXml, null, result.headers)
             .then(function (response) {
 
-                if (response.data['@Microsoft.Dynamics.CRM.fetchxmlpagingcookie'] != null) {
-                    response.data.PagingInfo = Utility.getFetchXmlPagingCookie(response.data['@Microsoft.Dynamics.CRM.fetchxmlpagingcookie'], pageNumber);
-                }
-
-                if (response.data['@odata.context'] != null) {
-                    response.data.oDataContext = response.data['@odata.context'];
+                if (response.data['@' + DWA.Prefer.Annotations.FetchXmlPagingCookie] != null) {
+                    response.data.PagingInfo = Utility.getFetchXmlPagingCookie(response.data['@' + DWA.Prefer.Annotations.FetchXmlPagingCookie], pageNumber);
                 }
 
                 return response.data;

lib/requests/helpers/parseResponse.js

@@ -1,4 +1,10 @@
-var dateReviver = require('./dateReviver');
+var DWA = require('../../dwa');
+var dateReviver = require('./dateReviver');
+
+//string es6 polyfill
+if (!String.prototype.endsWith || !String.prototype.startsWith) {
+    require("../../polyfills/string-es6");
+}
 
 //https://github.com/emiltholin/google-api-batch-utils
 function parseBatchResponse(response) {
@@ -20,16 +26,65 @@ function parseBatchResponse(response) {
     return result;
 }
 
+function populateFormattedValues(object) {
+    var keys = Object.keys(object);
+
+    for (var i = 0; i < keys.length; i++) {
+        if (object[keys[i]].constructor === Array) {
+            for (var j = 0; j < object[keys[i]].length; j++) {
+                object[keys[i]][j] = populateFormattedValues(object[keys[i]][j]);
+            }
+        }
+
+        if (keys[i].indexOf('@') == -1)
+            continue;
+
+        var format = keys[i].split('@');
+        var newKey = null;
+        switch (format[1]) {
+            case 'odata.context':
+                newKey = 'oDataContext';
+                break;
+            case 'odata.count':
+                newKey = 'oDataCount';
+                object[keys[i]] = object[keys[i]] != null
+                    ? parseInt(object[keys[i]])
+                    : 0;
+                break;
+            case 'odata.nextLink':
+                newKey = 'oDataNextLink';
+                break;
+            case DWA.Prefer.Annotations.FormattedValue:
+                newKey = format[0] + '_Formatted';
+                break;
+            case DWA.Prefer.Annotations.AssociatedNavigationProperty:
+                newKey = format[0] + '_NavigationProperty';
+                break;
+            case DWA.Prefer.Annotations.LookupLogicalName:
+                newKey = format[0] + '_LogicalName';
+                break;
+        }
+
+        if (newKey) {
+            object[newKey] = object[keys[i]];
+        }
+    }
+
+    return object;
+}
+
 /**
  *
  * @param {string} response
  */
 module.exports = function parseResponse(response) {
     var responseData = null;
     if (response.length) {
-        responseData = response.indexOf('--batchresponse_') > -1 
+        responseData = response.indexOf('--batchresponse_') > -1
             ? responseData = parseBatchResponse(response)[0]
             : responseData = JSON.parse(response, dateReviver);
+
+        responseData = populateFormattedValues(responseData);
     }
 
     return responseData;

lib/requests/sendRequest.js

@@ -63,9 +63,9 @@ module.exports = function sendRequest(method, uri, config, data, additionalHeade
             return value;
         });
 
-        stringifiedData  = stringifiedData.replace(/[\u007F-\uFFFF]/g, function(chr) {
+        stringifiedData = stringifiedData.replace(/[\u007F-\uFFFF]/g, function (chr) {
             return "\\u" + ("0000" + chr.charCodeAt(0).toString(16)).substr(-4)
-        })
+        });
     }
 
     //if the URL contains more characters than max possible limit, convert the request to a batch request

tests/common-tests.js

@@ -11,6 +11,7 @@ var ErrorHelper = require('../lib/helpers/ErrorHelper');
 var mocks = require("./stubs");
 var dateReviver = require('../lib/requests/helpers/dateReviver');
 var sendRequest = require('../lib/requests/sendRequest');
+var parseResponse = require('../lib/requests/helpers/parseResponse');
 
 describe("Utility.buildFunctionParameters - ", function () {
     it("no parameters", function () {
@@ -1296,7 +1297,6 @@ describe("sendRequest", function () {
             checkBody += rBodys[i];
         }
 
-        console.error(rBody + '!');
         before(function () {
             var response = mocks.responses.batch;
             scope = nock(mocks.webApiUrl + '$batch')
@@ -1321,7 +1321,7 @@ describe("sendRequest", function () {
         it("returns a correct response", function (done) {
             sendRequest('GET', url, { webApiUrl: mocks.webApiUrl }, null, null, function (object) {
                 var multiple = mocks.responses.multiple();
-                delete multiple.oDataContext;
+                //delete multiple.oDataContext;
                 var expectedO = {
                     status: 200,
                     headers: {},
@@ -1339,4 +1339,16 @@ describe("sendRequest", function () {
             expect(scope.isDone()).to.be.true;
         });
     });
+});
+
+describe("parseResponse", function () {
+    it("parses formatted values", function () {
+        var response = parseResponse(mocks.responses.responseFormatted200.responseText);
+        expect(response).to.be.deep.equal(mocks.responses.responseFormattedEntity());
+    });
+
+    it("parses formatted values - array", function () {
+        var response = parseResponse(mocks.responses.multipleFormattedResponse.responseText);
+        expect(response).to.be.deep.equal(mocks.responses.multipleFormatted());
+    });
 });

tests/stubs.js

@@ -23,6 +23,13 @@ var dataStubs = {
         name: "record",
         subject: "test"
     },
+    testEntityFormatted: {
+        name: "record",
+        subject: "test",
+        option: "value",
+        "@odata.context": "context",
+        "[email protected]": "formatted"
+    },
     updatedEntity: {
         fullname: "test record"
     },
@@ -45,6 +52,13 @@ var dataStubs = {
             { name: "name2", subject: "subject2" }
         ]
     },
+    multipleFormatted: {
+        "@odata.context": "context",
+        value: [
+            { name: "name1", subject: "subject1", option: "value", "[email protected]": "formatted" },
+            { name: "name2", subject: "subject2" }
+        ]
+    },
     multipleWithCount: {
         "@odata.context": "context",
         "@odata.count": 2,
@@ -199,6 +213,10 @@ var responseStubs = {
         status: 200,
         responseText: JSON.stringify(dataStubs.testEntity)
     },
+    responseFormatted200: {
+        status: 200,
+        responseText: JSON.stringify(dataStubs.testEntityFormatted)
+    },
     retrieveReferenceResponse: {
         status: 200,
         responseText: JSON.stringify(dataStubs.referenceResponse)
@@ -215,6 +233,10 @@ var responseStubs = {
         status: 200,
         responseText: JSON.stringify(dataStubs.multiple)
     },
+    multipleFormattedResponse: {
+        status: 200,
+        responseText: JSON.stringify(dataStubs.multipleFormatted)
+    },
     multipleWithCountResponse: {
         status: 200,
         responseText: JSON.stringify(dataStubs.multipleWithCount)
@@ -280,6 +302,12 @@ var responseStubs = {
             error: { message: "message" }
         })
     },
+    responseFormattedEntity: function () {
+        var stub = dataStubs.testEntityFormatted;
+        stub.oDataContext = stub["@odata.context"];
+        stub.option_Formatted = stub["[email protected]"];
+        return stub;
+    },
     multipleWithLink: function () {
         var stub = dataStubs.multipleWithLink;
         stub.oDataContext = stub["@odata.context"];
@@ -292,6 +320,12 @@ var responseStubs = {
         return stub;
 
     },
+    multipleFormatted: function () {
+        var stub = dataStubs.multipleFormatted;
+        stub.oDataContext = stub["@odata.context"];
+        stub.value[0].option_Formatted = stub.value[0]["[email protected]"];
+        return stub;
+    },
     multipleWithCount: function () {
         var stub = dataStubs.multipleWithCount;
         stub.oDataContext = stub["@odata.context"];