XrmServiceToolkit is a JavaScript library which could be used to make
- Common Methods: Change of CRM form like enable field, show field, etc
- Rest EndPoint Methods: Create, Retrieve, Update a record, etc
- Soap Request Methods: Create, Retrieve, Update a record, etc
- Extension Methods: Setup Dependent OptionSet, Add Tooltip to fields, Add custom filter view to lookup field. All these methods are generic to use and configurable through editing of XML web resource.
Debug / Unit Test JavaScript Rest or Soap in Visual Studio For CRM 2011
Project Highlight and Notes: Current Release - Version 1.4.1 (April, 2013)
New year has always been very busy for lots of people. There is no doubt for us, MSCRM consultants...
Last week, i got an email from Microsoft CRM team to notice me that my personal CRM online subscription will be updated to Rollup 12 which was exciting news because i finally have an environment to test and develop XrmServiceToolkit and make an effort to
support cross browser.
The upgrade obviously is a big deal for everyone. There are some immediate problems which i have seen for the toolkit after my instance is running RU12.
Version 1.4.0 is far from perfect at its current stage to support cross browser cause there are so many things to do and so much testing to be done. A quick summary for version 1.4.0 if you are keen.
* @current version : 1.4.1
* Date: April, 2013
* Dependency: JSON2, jQuery (latest or 1.7.2 above)
* Feature: Add Cross Browser Support for RU12, RU13
* Tested Platform: IE9, IE10, Chrome Version (latest), Firefox (latest)
If you have used the toolkit previously for your project, thanks very much for your support. For version 1.4.1, download and try it out using atesting environment and let me know issues and bugs.
Happy Coding,
Jaimie
For examples with qunit, please follow the links
Whats new:
- Version: 1.4.0
- Dependency: JSON2, jQuery 1.7.2 above
- Date: January, 2013
- New Feature: Add cross browser support for RU12
- Tested Browser: IE9, IE10, Chrome Version 24.0.1312.56 m, Firefox 18.0.1
- Version: 1.3.2
- Dependency: JSON2, jQuery 1.7.2 above
- Date: January, 2013
- New Fix: Fix an issue that XrmServiceToolit.Soap is not initialized properly when calling from ribbon for CRM Online
- Add more cross browser support before RU12
- Version: 1.3.1
- Dependency: JSON2, jQuery 1.7.2 above
- Date: November, 2012
- New Feature:
- A logic change to improvie performance when retrieving larger number of records
- New Function:
- XrmServiceToolkit.Soap.QueryAll: a method to return all records (>5k+). Similar to how to use XrmServiceToolkit.Soap.QueryByAttribute
- New Fix:
- XrmServiceToolkit.Rest.RetrieveMultiple not returning more than 50 records
- XrmServiceToolkit.Soap.BusinessEntity not working properly with number attribute like int, double, decimal
- XrmServiceToolkit.Soap not handling error message properly.
- Version: 1.3
- Dependency: JSON2, jQuery 1.7.2 above
- Date: July, 2012
- New Feature:
- jQuery integration
- Cross Browser support. More testings are required
- New Category and Extension:
- jQueryXrmDependentOptionSet: A generic configurable method to setup dependent option set in CRM 2011
- jQueryXrmFieldTooltip: A generic configurable method to setup tooltip for crm fields
- jQueryXrmLookupCustomFilterView: A generic configurable method to add custom filter view to crm lookup field
- Version: 1.2
- Dependency: JSON2
- Date: May, 2012
- New Fix - Create, Update, Retrieve activity with PartyList type [From, To, Cc, Bcc]
- Version: 1.1
- Depdendency: JSON2
- Date: April, 2012
- New Function - XrmServiceToolkit.Soap.Assign
- New Function - XrmServiceToolkit.Soap.GrantAccess
- New Function - XrmServiceToolkit.Soap.ModifyAccess
- New Function - XrmServiceToolkit.Soap.RevokeAccess
- New Function - XrmServiceToolkit.Soap.RetrievePrincipalAccess
Cross Browser Support
There is still a long way to go until calling the library to support real cross browser. As downloaded from Microsoft website, CRM 2011 code validation tool is used during the upgrade process. Though testings are insufficient
with real or RC environment of CRM 2011 RU9 o_0!
![Code Validation]()
Qunit Refresh and Test Results
Qunit plays a big part during the development and continous development for this project.[NOTE] Qunit is for unit testing. You do not need the part of the code in live code
![Qunit test result]()
Code Examples in the documentation.
All code examples or most of them are using in combination with Qunit. The qunit part of the code is not required in real life situation.
Synchronous and Asynchronous
The basics of synchronous and asynchronous calls are still the same without jQuery. As the reason not too sure yet , jQuery 1.8 will not support ajax asynch=false anymore. However in reality,
there will be still usage, for example onSave, synchronous calls might still required. For best practise, asynchronous calls should be used for better performance.
XrmServiceToolkit.Rest funcitons use the last boolean parameter to indicate if the method runs asychronously or synchronously. If false is assigned, then
the method will run synchronously, otherwise an asynchrounous method will be called.
var contact = {};
contact.FirstName = "Diane";
contact.LastName = "Morgan";
contact.MiddleName = "<&>";
contact.GenderCode = { Value: 2 };
contact.CreditLimit = { Value: "2.00" };
contact.BirthDate = birthDate;
contact.DoNotEMail = true;
contact.DoNotPhone = true;
XrmServiceToolkit.Rest.Create(
contact,
"ContactSet",function (result) {
contactId = result.ContactId;
},function (error) {
alert(error.message);
},false //synchronous call
); var contact = {};
contact.FirstName = "Diane";
contact.LastName = "Morgan";
contact.MiddleName = "<&>";
contact.GenderCode = { Value: 2 };
contact.CreditLimit = { Value: "2.00" };
contact.BirthDate = birthDate;
contact.DoNotEMail = true;
contact.DoNotPhone = true;
XrmServiceToolkit.Rest.Create(
contact,
"ContactSet",function (result) {
contactId = result.ContactId;
},function (error) {
alert(error.message);
},true //asynchronous call
);
XrmServiceTookit.Soap functions using the last function parameter to indicate if the method runs asychronously or synchronously. If the funciton is defined,
the method will run asychronously. Otherwise, the method will be called synchronously.
var cols = ["firstname", "lastname", "middlename", "familystatuscode", "ownerid", "creditlimit", "birthdate", "donotemail", "donotphone"];var retrievedContact = XrmServiceToolkit.Soap.Retrieve("contact", contactId, cols); //synchronous callvar familyStatusLable = retrievedContact.attributes['familystatuscode'].formattedValue;var firstName = retrievedContact.attributes['firstname'].value;var cols = ["firstname", "lastname", "middlename", "familystatuscode", "ownerid", "creditlimit", "birthdate", "donotemail", "donotphone"];
XrmServiceToolkit.Soap.Retrieve("contact", contactId, cols, function(result){ var familyStatusLable = result.attributes['familystatuscode'].formattedValue; var firstName = result.attributes['firstname'].value;
}); //asychronous callNumbers
CRM 2011 has number like whole number (int), floating point (double) and Decimal number (decimal), Currency (Money).
When using the soap funcitons in the library, it is recommended to include type when assigning values. It is more likely to cause issue for fields like decimal or double
//overcome limitations of numbers with type specified....
createContact.attributes["numberofchildren"] = { value: 2, type: "int"};
createContact.attributes["exchangerate"] = {value: 1.5617, type: "decimal"};
createContact.attributes["address1_latitude"] = { value: 1.5617, type: "double" };
createContact.attributes["creditlimit"] = { value: 2, type: "Money" }; FormattedValue
The XrmServiceToolkit.Soap functions have an extra attribute returned as formattedValue. It could be very useful if you want to return some extra information. For example, to get the lable of OptionSet.
The example is synchrous.
var cols = ["firstname", "lastname", "middlename", "familystatuscode", "ownerid", "creditlimit", "birthdate", "donotemail", "donotphone"];var retrievedContact = XrmServiceToolkit.Soap.Retrieve("contact", contactId, cols);var familyStatusLable = retrievedContact.attributes['familystatuscode'].formattedValue;//labelvar familyStatusValue = retrievedContact.attributes['familystatuscode'].value; //integerAn example to create email activity using the library.
test("Test XrmServiceToolkit.Soap.Create() method to create a email activity (email)", function () {var createEmail = new XrmServiceToolkit.Soap.BusinessEntity("email");
createEmail.attributes["subject"] = "Test Email subject";
createEmail.attributes["description"] = "This email was created by the XrmServiceToolkit.Soap.Create() sample.";var from = [
{ id: whoamiUserId, logicalName: "systemuser", type: "EntityReference" }
];
createEmail.attributes["from"] = { value: from, type: "EntityCollection" };var to = [
{ id: accountId, logicalName: "account", type: "EntityReference" },
{ id: contactId, logicalName: "contact", type: "EntityReference" }
];
createEmail.attributes["to"] = { value: to, type: "EntityCollection" };var cc = [
{ id: accountId, logicalName: "account", type: "EntityReference" },
{ id: contactId, logicalName: "contact", type: "EntityReference" }
];
createEmail.attributes["cc"] = { value: cc, type: "EntityCollection" };var bcc = [
{ id: accountId, logicalName: "account", type: "EntityReference" },
{ id: contactId, logicalName: "contact", type: "EntityReference" }
];
createEmail.attributes["bcc"] = { value: bcc, type: "EntityCollection" };
createEmail.attributes["directioncode"] = true;
emailId = XrmServiceToolkit.Soap.Create(createEmail);
ok(guidExpr.test(emailId), "Creating an email should returned the new record's ID in GUID format. ");
});An example to retrieve an email is like this. The returned value of [From/To/Cc/Bcc] is an array of Entity reference.
test("Test XrmServiceToolkit.Soap.Retrieve() method to retrieve a CRM record (email)", function () {var cols = ["subject", "description", "from", "to", "cc", "bcc", "directioncode"];var retrievedEmail = XrmServiceToolkit.Soap.Retrieve("email", emailId, cols);
equals(retrievedEmail.attributes['subject'].value, "Test Email subject", "Subject matches");
equals(retrievedEmail.attributes['description'].value, "This email was created by the XrmServiceToolkit.Soap.Create() sample.", "Description Matches");
equals(retrievedEmail.attributes['from'].type, "EntityCollection", "CRM partylist type should be EntityCollection");
equals(retrievedEmail.attributes['to'].type, "EntityCollection", "CRM partylist type should be EntityCollection"); ;
equals(retrievedEmail.attributes['cc'].type, "EntityCollection", "CRM partylist type should be EntityCollection");
equals(retrievedEmail.attributes['bcc'].type, "EntityCollection", "CRM partylist type should be EntityCollection");
equals(retrievedEmail.attributes['directioncode'].type, "boolean", "CRM boolean type should be boolean");
});To get the value of an array item of the returned result. Using something like
var sender = retrievedEmail.attributes['from'].value[0];
Then you can get sender.id, sender.type, sender.logicalName, sender.Name per normal as a returned EntityReference value.
An example to use the GrantAccess is like this. For all other examples, please have a look at the attached aspx page.
test("Test XrmServiceToolkit.Soap.GrantAccess() method to grant a user access to a CRM record (contact)", function () {var accessOptions = {
targetEntityName: "contact",
targetEntityId: contactId,
principalEntityName: "systemuser",
principalEntityId: currentUserId,
accessRights: ["ReadAccess", "WriteAccess"]
};var grantAccessResponse = XrmServiceToolkit.Soap.GrantAccess(accessOptions);
ok(grantAccessResponse == "GrantAccess", "The current user should have the listed access to the contact");
});
[NOTE] These functions regarding access should be combined with CRM 2011 security model and they could be useful if entities have to be controlled at record level. This obviously has to be used with consideration of user rights,
security settings and all other security related configurations as the requirement of the project.
For details about how to use all these methods and updated examples. See attached .aspx page for examples.
Credi: The code example is based on Daniel Cai's CrmWebServiceKit.
XrmServiceToolkitTest.zip
Dependency
JSON2 javascript library is required in CRM 2011 as a web resource to make the library working.
jQuery 1.7.2 above is required from version 1.3
To Unit Test your code at local machine.
There is a way to test all your Rest / Soap calls directy from your development machine without modifying the library which is achieved by using the XrmPageTemplate.js and PageData.js. For details about how to using JavaScript Intellisense, please have a look
at this wonderful blog
http://crmbusiness.wordpress.com/2011/12/01/crm-2011-using-javascript-intellisense-and-testpage-htm/
Once you have got the PageData.js generated from any entity, simply put it in the helper folder to replace the existing PageData.js in the source code project which you could download from the [Source Code] section here.
Now you could run and debug the XrmServiceToolkitTest.aspx from your visual studio.
Happy Coding,
Jaimie