Xrm.Page.context.getVersion is now a supported method, use it!

Recently the MSDN page regarding the Client-side context methods of Dynamics 2016/365 has been updated and thanks to the Dynamics team a new method is inside the documentation: Xrm.Page.context.getVersion.

Some developers are already using this method in their code, personally I didn't because I had not the necessity to differentiate between the 8.x endpoints.

The method returns a string containing the full version in the Major.Minor.Build.Revision format, an example is "8.2.1.185".

In the previous CRM versions if we want to get the version from the client we had two ways:

• call the RetrieveVersionRequest message using the SOAP endpoint (example)
• check if a specific CRM function exists (example)

I used often the second way because I always considered doing a server call (often synchronous) not a good choice for the script performance.

Why we want to know the current CRM version? Because some functions are available only from a specific version, like the one to execute a workflow: the Microsoft.Dynamics.CRM.ExecuteWorkflow introduced with the 8.2 release.

But for the Web API endpoint we need to provide only Major.Minor and not the full version, therefore a transformation is necessary.

The following code maybe will be considered exaggerated by someone but creating a robust piece of code will reduce the necessity to change the script in the future:

function getCurrentVersion(context) {
    if (context.getVersion == undefined) { return ""; }
    var versionArray = context.getVersion().split(".");
    if (versionArray.length < 2) { return ""; }
    return versionArray[0] + "." + versionArray[1]; 
}

The result from the "8.2.1.125" is "8.2" ready to be inserted inside your Web API url.

Few considerations:

• If the version cannot be retrieved I decided to return an empty string, but you can return null, throw an exception, call another method, set a default value, etc etc...
• the function requires the context, in this way you can use in the form scripts (like an onload event) or inside a WebResource
• I decided to split the string to an array using the dot (.) I think this is the most robust way compared to doing a substring or expecting a second dot in the string

CRM 2016 Web API and plural names

The new Web API available for CRM 2016 is based on OData V4 protocol and the endpoint is /api/data/v8.0/

The MSDN contains several examples of the new endpoint, for example if we want to retrieve the top 3 accounts:

/api/data/v8.0/accounts?$select=name&$top=3

Simple, right? if you want to retrieve from account entity you write accounts, if you want to retrieve from contact entity you write contacts, if you want to retrieve from opportunity entity you write opportunities. You write the plural.

What a poor choice to use the plural form instead of the singular one, and let me say something, the root of the problem is an English-centered vision.

I'm not an expert of REST and OData protocols, maybe they suggest to use the plural forms but when you let users dynamically add entries to the endpoint (i.e. creating an entity) the use of plural forms is a mess.

A user on Dynamics Community asked a question: "my custom entity name is xxx_settings and I can't query using the endpoint /api/data/v8.0/xxx_settingss, which is the right syntax?"

Well, in this case the answer is simple, who designed the API decided to apply the exceptions, so if the noun ends with s the plural is es, in the user's case the correct endpoint is /api/data/v8.0/xxx_settingses, but if you want to be sure about the name you can check the metadata at this url: /api/data/v8.0/ or download the XML from the Developer Resources inside CRM UI.

Now let's play a game, how much are robust the exceptions they implemented in order to create the plural form? The answer is weak.
English is not my first language so I googled "plural exceptions english" and I landed in this page: A handout on irregular plural noun forms. I started to create some custom entities, here some results:
new_city become new_cities, English correct.
new_wolf become new_wolfs, English incorrect.
new_knife become new_knifes, English incorrect.
new_man become new_mans, English incorrect.

Now, I don't expect that all the irregular forms are covered, but if you decide to handle the final 's' and the final 'y' why not handle the final 'f'? However not big deal, You check the metadata and you can find the exact plural word to use.

BUT, and there is a BUT

Let's say we created our custom entity new_city and now the REST endpoint responds to /api/data/v8.0/new_cities, what will happen if we create a custom entity called new_citie?
The entity is not listed inside the REST endpoint!!! because the plural of new_citie is new_cities but it's already used by new_city.
The lesson is: pay attention when you name your entities if you need to query them using the new REST endpoint, if the plural form of a new entity is the same of the plural form of a previous entity, you can't query it.