CRM SOAP Library- Part 3 (Testing CRM web resources for CRM Online in Visual Studio)

This is a part 3 of the CRM Soap Library series. This blog covers how to test the web resources that make CRM web services calls  from visual studio for MSCRM Online.

If you run the CRM soap library sample or "StartUp.htm" page from my last blog CRM SOAP Library - Part 2 (Project Structure) , you will get the following  error.

“Sdk.Util.getClientUrl Unable to get clientUrl. Context not available.”

This is a straight forward error. The library is trying to get the CRM URL from global context or Xrm.page.Context. For development purposes,  you can replace the “GetGlobalContext().getClientUrl()” line in “Sdk.Soap.min.js” with your  CRM Online URL.


Now if you try to run the code after making the change,  code will throw the following error.

“status: 401: Unauthorized”

It becomes a pain when you have to keep deploying Java Script resources to CRM to test them. There are hundreds of forums/blogs that talk about this problem but you can’t not see any solution.

I figured out a way around this problem with the help of “Fiddler”.So, here is hack that will allow you to run/test you web resources without deploying them in CRM.

Here is the step by step tutorial to achieve this.

1. If you don't have fiddler installed already, install it.you can download it from http://www.telerik.com/download/fiddler.
   
2. Start the fiddler and make sure “Capture Traffic” is selected  in the “File” menu as shown in the screen shot below.
    
   
3. Logon to your CRM organisation. I am using CRM Online for this tutorial.
   
4. Switch to fiddler and double click on  a CRM URL from the session pane as shown in the screen shot.
   
   
5. In the second pane, select “Inspectors>>Cookies” as shown in the screen shot below. if the contents of cookies for the selected request does not look the same try some other URL from the session list.
   
   
6. Look for “MSISAuth” in the contents and select everything from that text onwards and paste it notepad.
   
7. Select “Tools>>Customize Rules” as shown in the screen shot below. It will open the “CustomRules.js” file.
   
8. Search for  “OnBeforeRequest(oSession: Session) function in the file and add the following code to it.
   
   

   1:  if (oSession.PathAndQuery=="/XRMServices/2011/Organization.svc/web")  
   2:   {  
   3:               //appending the cookie data for the request  
   4:            oSession.oRequest["Cookie"] = (oSession.oRequest["Cookie"] + "; text copied in step 6" );  
   5:  }  
   
   

   
   
9. Replace the highlighted text with the text copied in step 6. Save the changes to the file.
   
10. Open up your HTML page in VS and test it. You won’t get the unauthorised error  anymore.

CRM SOAP Library - Part 2 (Project Structure)

This is the second part of my blog www.mscrmshop.blogspot.com.au/2015/10/crm-soap-library-sdksoapjs-part-1.html. In this blog I will discuss the Visual Studio project structure for JavaScript(SOAP endpoints) projects. The sample project provided by Microsoft has the following structure.



All the code is contained in the folder '_samples'. There are 3 sub folders in that folder.

• min:
  This folder contains the minified version of Sdk.soap.min.js, jquery_1.9.1.min.js and folders for actions, entities and messages.
• sampleCode:
  This is working folder where developers will write their html and JavaScript  web resources. This folders contains 3 subfolders to organise the images, pages(html), and scripts.
• vsdoc:This folder contains all the same files and folders as the 'min' folder but they are not min-ified. Libraries in this folder contains comments etc. for the developer. Script files from this folder will be used in sampleCode scripts to provide IntelliSense.

Project Template

I think development teams should use project templates if they are doing similar work all the time. It brings consistency onto the project structure. I have changed a few things around in the sample project and turned it into a project template. My project structure looks like the following screen shot.

 

I got rid of the '_sample' folder. I have renamed the 'min' folder to 'libs' as this folder also contains the SOAP library as well as the jquery library. I have renamed 'sampleCode' to 'webresources' and left the vsdoc as it is. I have deleted most of the sample files from this solution as I want to use this project as a project template. I have kept a few files from the sample solution to use as templates if required.

You can download my project template from: Project Template.

Now when developers will starts a webresource project using the soap endpoint. They will select a project type of “CRM SOAP JavaScript” project as shown in the following screen shot.



By doing that you  have same folder structure for all webresource projects using SOAP endpoints.

The following screen shot displays the structure of the new project created using the template.

Working with the files

1. libs folder
   The following screen shot displays all the files and sub folders in the libs folder. The most important thing to remember is to use the min-ified version of all the JavaScript files to reduce the size. 
   

• the root folder contains the Sdk.soap.min.js and jquery_1.9.1.min.js files

• the 'actions' folder contains all the custom action classes. The custom action will be created using Sdk.Soap.js Action Message Generator.

• the 'entities' folder contains all the CRM entity classes. These classes will be used for early binding.

• the 'message' folder contains all the other messages supported by the library. The library supports 202 different messages. You can add and remove the messages required by your project.

2. vsdocs folder
   This folder contains all the files and folders as the 'libs' folder. The only difference is that the JavaScript files in this folders are not min-ified. These files will be used just for IntelliSense and won’t be uploaded into CRM.

3. webresources folder
   This is the real working folder. This folder contains the following files and folders:
   

• the 'images' folder contains all the images used in the HTML web resources.

• the 'pages' folder contains all the HTML websesources

• the 'scripts' folder contains all the JavaScript files that will be called by the html webresources/CRM forms.

I have added a StartUp.htm and StartUp.js to the project template as starting webresources. You can modify them for your project or use as reference.
The following section displays the source code for StartUp.htm



1:  <html>  
2:  <head>  
3:   <title>StartUp Page</title>  
4:   <script src="../../../ClientGlobalContext.js.aspx" type="text/javascript"></script>  
5:   <script src="../../libs/Sdk.Soap.min.js"></script>  
6:   <script src="../../libs/jquery_1.9.1.min.js"></script>  
7:   <script src="../../libs/entities/Sdk.Account.min.js"></script>  
8:   <script src="../scripts/StartUp.js"></script>  
9:   <!--<script src="../../libs/messages/Sdk.WhoAmI.min.js"></script>   
10:   <script src="../../libs/actions/Sdk.sample_SimpleAction.min.js"></script>-->  
11:   <script type="text/javascript">  
12:   "use strict";  
13:   document.onreadystatechange = function () {  
14:    if (document.readyState == "complete") {  
15:    }  
16:   }  
17:   function clearMessages() {  
18:    document.getElementById("messages").innerHTML = "";  
19:   }  
20:   function earlyBindingSample() {  
21:    clearMessages();  
22:    writeToPage("Starting 'Early Binding' Sample");  
23:    try {  
24:    startEarlyBindingSample();  
25:    }  
26:    catch (e) {  
27:    writeToPage(e.message);  
28:    }  
29:   }  
30:   </script>  
31:   <style type="text/css">  
32:   body  
33:   {  
34:    font-family: "Segoe UI";  
35:   }  
36:   </style>  
37:  </head>  
38:  <body>  
39:   <button onclick="earlyBindingSample()">&quot;Early Binding&quot; Sample</button>  
40:   <ol id="messages" />  
41:  </body>  
42:  </html>  


The script section highlighted in yellow lists all the JavaScript files required for this webresource. You can add the reference to your custom actions, entities and messages as required.

• ClientGlobalContext.js.aspx:
  This file will get the context for the webresource


• scripts/Sdk.Startup.js:
  This file contains the startEarlyBindingSample() function that the StartUp.htm webresource will call.

The following code displays the reference directive from the StartUp.js. 



1:  /// <reference path="../../vsdoc/Sdk.Soap.vsdoc.js" />  
2:  /// <reference path="../../vsdoc/entities/Sdk.Account.vsdoc.js" />  
3:  /// <reference path="../../vsdoc/jquery_1.9.1_vsdoc.js" />  

These directives are used to provide IntelliSense. You can read the following article to get detail information on JavaScript IntelliSense. https://msdn.microsoft.com/en-us/library/bb385682.aspx  As you can see the code above references “Sdk.Account.vsdoc.js”. It will add the IntelliSence for the account entity as shown in the screen shot below.



That is all about the project structure. I hope this will give you enough information on how to setup a project structure for the Sdk.soap.js library.


Another feature that would be nice, would be a one click deployment into CRM...

CRM SOAP Library – sdk.soap.js Part 1

This blog post is related to the CRM soap library created by the CRM SDK team last year. This library helps with writing JavaScript for web resources using SOAP endpoints just like C# code.  I am surprised that it only has 2600 downloads. I believe more people should use it. It provides a lot of functionality and will help to reduce code duplication in a project.
The library includes 2 files:

• Sdk.Soap.min.js This is the minified version of the library. The size of the file is around 164kb.
• Sdk.Soap.vsdoc.jsThis file should be used at design time to add IntelliSense to JavaScript

Advantages/Benefits

The following lists some of the benefits/advantages of using this library.

1. Writing JavaScript like C#
   The library helps you to write JavaScript like C# code. It provides object models, methods and messages like C#. It is more productive if you are a C# developer.

2. IntelliSense
   The Sdk.Soap.vsdoc.js file contains comments for the developers. It will be used at design time to provide IntelliSense. You just need to add a reference directive on the top of your .js file as shown below:
   /// <reference path="..path/Sdk.Soap.vsdoc.js" />

3. Choice of Early Bound and Late Bound Classes
   The library provides the option to chose early binding and late binding in your code. I prefer the late binding but other people may prefer early binding classes as it provides the IntelliSense at design time for CRM entities. The solution also provides an early binding class entities generator to generate early bind classes for CRM entities. It is an equivalent of  crmserviceutil.exe

4. Choice of Namespaces
   The library supports the following 8 core IOrganisationService methods.
   Associate,Create, Delete, Disassociate, Execute, Retrieve, RetrieveMultiple and Update.
   
   The library provides the 4 different namespaces that implement these core methods:



• Sdk.Async:  It executes the methods asynchronously. The method signatures provide the  successCallBack and errorCallBack parameters.
• Sdk.Sync:  It executes the methods synchronously.
• Sdk.jQ:  It is an alternative approach to implementing asynchronous operations. It returns a jQuery.Deferred object/Promise. The initial state of the object is pending. The code will wait until the promise is resolved or rejected to execute the next line of the code.  In short, it is like writing synchronous code for asynchronous calls. I will post some sample code to explain the difference between callbacks and promises at a later date.
  
  This namespace depends on the existence of the jQuery.
             
• Sdk.Q:This is also the implementation of the “Promise” concept discussed above in Sdk.JQ.


5. Messages/Actions
   Apart from the 8 core methods, the library supports 202 different methods. The library also provides a utility to create methods for custom action methods.


6. Supported Queries
   The Sdk.Soap.js library supports the three main query styles used with retrieve operations:

• QueryByAttribute

• FetchExpression

• QueryExpression

Things to consider

1. The library was originally written for CRM2013. The Sdk.Xml.getEnvelopeHeader function specifies an SdkClientVersion value of 6.0. It does work for CRM2013 and CRM2015. It may change in future.
2. It does not contain all the messages.Please check the documentation on the libarary page.
3. Delete the messages that are not required for your project to reduce the size of the JavaScript file.
4. Delete the namespaces that are not required

Downloads

Here is the list of the downloads for the library:

1. Sdk.Soap.js (contains the core libraries)

2. Sdk.Soap.js Entity Class Generator (tool to create libraries for CRM entities for ‘early binding’ and IntelliSense)

3. Sdk.Soap.js Action Message Generator (tool to generate the support libraries for custom actions in your organization.

4. Sdk.Soap.js Samples (code sample using the library)