Release: MSCRM4 Web Service Toolkit for JavaScript v2.1

Today I am pleased to announce the release of CRM Web Service Toolkit for JavaScript v2.1. The new release includes the following enhancements:

• All the major functions now support asynchronous calls through an optional callback function parameter. When the callback function is provided, the toolkit will perform an asynchronous service call, otherwise it would be a synchronous call. 
• A new function setState has been added to the toolkit, which allows you to update a CRM record's status.
• Two functions (associate, disassociate) have been added to the toolkit, which you can use to associate or disassociate two CRM records that have an N:N relationship. 
• The signature of queryByAttribute function has been changed, so it takes one parameters now, instead of a bunch of optional parameters in previous version.

In order to make use of the toolkit, you can refer to my previous release page for sample code of all major functions.

Here are a few additional samples that can help you get up to speed with the new release.

1. Use the optional asynchronous callback function. As just mentioned, all major functions now support asynchronous calls. The asynchronous callback function should take single parameter which is whatever you are expecting to get by using the synchronous call. For instance, if you make an asynchronous call to CrmServiceToolkit.Fetch() method, your callback function should be dealing with the fetch result which is an array of BusinessEntity as the single parameter. Here is a quick sample.
   

   // callback function
   function fetchCallback(fetchedContacts) {
       alert(fetchedContacts.length);
       alert(fetchedContacts[0].getValue('lastname'));        
       alert(fetchedContacts[0].getValue('creditlimit'));
       alert(fetchedContacts[0].getValue('creditlimit', 'formattedvalue'));
       alert(fetchedContacts[0].getValue('birthdate'));
   };
   
   // Fetch all contact records whose first name is John using FetchXML query
   var firstname = 'John';
   var fetchXml = [
   "<fetch mapping='logical'>",
      "<entity name='contact'>",
         "<attribute name='contactid' />",
         "<attribute name='firstname' />",
         "<attribute name='lastname' />",
         "<attribute name='creditlimit' />",
         "<attribute name='birthdate' />",
         "<filter>",
            "<condition attribute='firstname' operator='eq' value='", firstname, "' />",
         "</filter>",
      "</entity>",
   "</fetch>"
   ].join("");
   
   // Use CrmServiceToolkit.Fetch() to make an asynchronous call.
   var fetchedContacts = CrmServiceToolkit.Fetch(fetchXml, fetchCallback);
   

2. Use CrmServiceToolkit.setState() to update a CRM record's status.
   

   // Use CrmServiceToolkit.setState() to update a CRM record's status. 
   var contactId = '3210F2BC-1630-EB11-8AB1-0003AAA0123C';
   var response = CrmServiceToolkit.setState('contact', contactId, 'Inactive', 2);
   alert(response);

3. Use CrmServiceToolkit.associate() to associate two CRM records that have an N:N relationship.
   

   // Use CrmServiceToolkit.associate() to associate two CRM records that have an N:N relationship. 
   var contactId = '3210F2BC-1630-EB11-8AB1-0003AAA0123C';
   var orderId = '3210F2AF-1630-EB11-8AB1-0003AAA0126A';
   var response = CrmServiceToolkit.associate('contactorders_association', 'contact', contactId, 'salesorder', orderId);
   alert(response);

4. Use CrmServiceToolkit.disassociate() to disassociate two CRM records that have an N:N relationship.
   

   // Use CrmServiceToolkit.disassociate() to disassociate two CRM records that have an N:N relationship. 
   var contactId = '3210F2BC-1630-EB11-8AB1-0003AAA0123C';
   var orderId = '3210F2AF-1630-EB11-8AB1-0003AAA0126A';
   var response = CrmServiceToolkit.disassociate('contactorders_association', 'contact', contactId, 'salesorder', orderId);
   alert(response);

5. Use CrmServiceToolkit.queryByAttribute() to retrieve all CRM records that match the query criteria.
   

   // Use CrmServiceToolkit.queryByAttribute() to retrieve all CRM records that match the query criteria. 
   var queryOptions = {
       entityName : "contact",
       attributes : ["firstname", "lastname"], // Search by firstname and lastname
       values : ["John", "Smith"], // Find all contacts whose firstname is John, lastname is Smith
       columnSet : ["familystatuscode", "creditlimit", "birthdate"],
       orderby : ["creditlimit", "birthdate"]
   };
   
   var fetchedContacts = CrmServiceToolkit.queryByAttribute(queryOptions);

For all the rest functions, you should be able to find related sample code from my previous release page.

[CREDITS]

• The idea behind CrmServiceToolkit.BusinessEntity was inspired by Ascentium CrmService JavaScript Library, after I have finished most of version 1.0 coding. Hats off to Ascentium CRM practice team.
  
• Thanks to Daniel René Thul for his contribution on the implementation of asynchronous support in this release.
  

P.S. Please excuse me that I have to break my word in the previous release page, guess this would be the last release before CRM5. :-)

[Update - Oct 16, 2010] A bug fix has been included in the release so that the BusinessEntity can work properly with null value now.