The crmfetchkit's intro from casperj

#Introduction Browser library that allows the execution of fetchxml-queries via JavaScript for Dynamics CRM using SOAP endpoint.

Like the CrmRestKit.js depdends this framework on the promise concept, but it uses bluebird instead of jQuery to manage the complexity of asynchronous operation.

The code and the idea for this framework bases on the CrmServiceToolkit developed by Daniel Cai.

#Topics

Support
Documentation
Installation
Build
Testing
Versions

#Support ##Version 3.x The version 3.x supports Chrome, Firefox and IE9+ and was tested with Dynamics CRM 2013 Online and Dynamics CRM 2015 Online.

##Version 2.x The version 2.x supports Chrome, Firefox and IE8+ and was tested with Dynamics CRM 2013 Online.

#Documentation In case the provided samples in this section are not sufficient, please review the integration tests.

##GetById Instead of create a fetchxml query for a very simple query, this method should be used to load an records based on the id.

var accountid = '06887701-2642-4a53-99ba-c24ce1a5688b',
	columns = ['name', 'donotfax', 'donotemail', 'createdon'];

CrmFetchKit.GetById('account', accountId, columns).then(function(account) {

		console.log(account.getValue('name'));

	});

##GetByIdSync

var accountid = '06887701-2642-4a53-99ba-c24ce1a5688b',
	columns = ['name', 'donotfax', 'donotemail', 'createdon'],
	account;

account = CrmFetchKit.GetByIdSync('account', accountId,  columns);

console.log(account.getValue('name'));

##Fetch With the Fetch method is it possible to execute fetch-xml based query. The method will resolve the promise with an array of BusinessEntity objects. These type supports the method getValue(<%attributename%>).

The following code load all account records with the name foobar and prints the names to the console.

var fetchxml = [
	'<fetch version="1.0">',
	'  <entity name="account">',
	'    <attribute name="name" />',
	'    <attribute name="accountid" />',
	'    <filter type="and">',
	'      <condition attribute="name"',
	'          operator="eq" value="foobar" />',
	'    </filter>',
	'  </entity>',
	'</fetch>'].join('');

CrmFetchKit.Fetch(fetchxml).then(function(entities){

	for(var i = 0, max = entities.length; i < max; i++) {
		console.log(entities[0].getValue('name'))
	}
});

##FetchSync

var fetchxml = [
	'<fetch version="1.0">',
	'  <entity name="account">',
	'    <attribute name="name" />',
	'    <attribute name="accountid" />',
	'    <filter type="and">',
	'      <condition attribute="name"',
	'          operator="eq" value="foobar" />',
	'    </filter>',
	'  </entity>',
	'</fetch>'].join('');

var entities = CrmFetchKit.FetchSync(fetchxml);

for(var i = 0, max = entities.length; i < max; i++) {
	console.log(entities[0].getValue('name'))
}

##FetchMore In a situation where the developer needs more control over the loaded data, the FetchMore method should be used. The method will resolve the promise with an object that supports the following properties:

totalRecordCount (number)
moreRecords (boolean)
pagingCookie (string)
entityName (string)
entities (array ob BusinessEntity objects)

var fetchxml = [
	'<fetch version="1.0"',
	'	returntotalrecordcount="true" ',
	'	count="10">',
	'  <entity name="contact">',
	'    <attribute name="lastname" />',
	'    <attribute name="contactid" />',
	'    <filter type="and">',
	'      <condition attribute="lastname" ',
	'           operator="like" value="foobar" />',
	'    </filter>',
	'  </entity>',
	'</fetch>'].join('');

CrmFetchKit.FetchMore(fetchxml).then(function(response){
	console.log(response.totalRecordCount);
	console.log(response.moreRecords);
	console.log(response.entityName);
	console.log(response.pagingCookie);

	for(var i = 0, max = response.entities; i < max; i++){
		console.log(response.entities[i].getValue('lastname'));
	}
	});

##FetchMoreSync

var fetchxml = [
	'<fetch version="1.0"',
	'	returntotalrecordcount="true" ',
	'	count="10">',
	'  <entity name="contact">',
	'    <attribute name="lastname" />',
	'    <attribute name="contactid" />',
	'    <filter type="and">',
	'      <condition attribute="lastname" ',
	'           operator="like" value="foobar" />',
	'    </filter>',
	'  </entity>',
	'</fetch>'].join('');

var CrmFetchKit.FetchMoreSync(fetchxml);

console.log(response.totalRecordCount);
console.log(response.moreRecords);
console.log(response.entityName);
console.log(response.pagingCookie);

for(var i = 0, max = response.entities; i < max; i++){
	console.log(response.entities[i].getValue('lastname'));
}

##FetchAll To address the 5.000 records query limit of Dynamics CRM (a single request return at a maximum 5.000 records) provides the CrmFetchKit with the FetchAll method an option to load all records retunred by an query.

Note: This method supports only the asynchronous execution.

// query loads all contact records in the system
var fetchxml = [
	'<fetch version="1.0">',
	'  <entity name="contact">',
	'    <attribute name="lastname" />',
	'    <attribute name="contactid" />',
	'  </entity>',
	'</fetch>'].join('');

CrmFetchKit.FetchAll(fetchxml).then(function(entities){

	for(var i = 0, max = entities.length; i < max; i++) {
		console.log(entities[i].getValue('lastname'));
	}
});

Internally uses FetchAll the FetchMore method and the provided pagingCookie to load the pages until all records are loaded.

##FetchByPage This method allows the load of records per page-number.

// load records from the first page
CrmFetchKit.FetchByPage(fetchxml, 1).then(function(responsePage1) {
                            
	// load records form the second page
    return CrmFetchKit.FetchByPage(fetchxml, 2, responsePage1.pagingCookie)
        .then(function(responsePage2){
            
            //...
        });
})

##Assign The Assign method allows the modification of the owner of an CRM record.

var contactid = '06569fb8-88d0-4588-bdb8-c20c19e29205',
// the team is the new owner of the concact record
teamid = '4797f323-76ac-4cf7-8342-b7c1bafd5154';

CrmFetchKit.Assign(contactid, 'contact', teamid, 'team').then(function(){

	//..
});

##AssignSync

var contactid = '06569fb8-88d0-4588-bdb8-c20c19e29205',
	// the team is the new owner of the concact record
	teamid = '4797f323-76ac-4cf7-8342-b7c1bafd5154';

CrmFetchKit.AssignSync(contactid, 'contact', teamid, 'team');

Note: The parameter for this method have change form the 1.x version of the CrmFetchKit. The old version supported only the assignment of SystemUsers where the current version supports Teams and SystemUsers.

###Support for Joins FetchXml support the joining via the "link-entity" tag. In case the query yields attributes of the linked entity, an alias must be provided to access these attributes with the getValue() method of the business-entity object.

The following query uses the alias bu to identify the attributes of the joined entity businessunit:

// the query loads all account records that belong to the root business unit
var fetchxml = [
	'<fetch version="1.0">',
	'  <entity name="account">',
	'    <attribute name="name" />',
	'    <link-entity name="businessunit" from="businessunitid"',
	'           to="owningbusinessunit" link-type="inner" alias="bu">',
	'       <attribute name="name" />',
	'       <filter>',
	'           <condition attribute="parentbusinessunitid" operator="null" />',
	'       </filter>',
	'   </link-entity>',
	'  </entity>',
	'</fetch>'].join( '' );

In order to access the attributes of the buinsess-unit record, the notation <%ailas%>.<%attributename%> must be used:

CrmFetchKit.Fetch(fetchxml).then(function(entities){

var first = entities[0];

console.log('Name of the business-unit: ' + first.getValue('bu.name'));
console.log('Name of the account: '+ first.getValue('name'));
});

###Support for asynchronous and synchronous execution The methods Fetch, FetchMore and Assign support the options parameter opt_async (default is set to true). Due to the default value, will the library execute the operation in asynchronous mode when the very last parameter is omitted.

CrmFetchKit.Fetch(query);

To executed the operation in synchronous mode, the last parameter must be set to false when invoking the function

CrmFetchKit.Fetch(query, false);

The method FetchAll supports only the asynchronous execution.

#Installation The GitHub folder build hosts two file: CrmFetchKit.bundle.js, CrmFetchKit.min.js, just download one of these files and deploy the script as web-resource to your CRM server.

Note: The library uses bluebird for the promise features. The build step (gulp) generates the file CrmFetchKit.bundle.js and this file already contains bluebird. So it is not necessary to deploy bluebird as additional web-resource to Dynamics CRM.

##Bower.io This module could be installed via bower:

bower install crmfetchkit

##npm package This module could be installed via npm, the first version supporting npm is 3.2.0:

npm install crmfetchkit

##Build To build the library from source-code the following components are required:

Node.js
bower.io

Open the command line, navigate to the root folder and enter the following command:

npm install

This will install all the needed node.js packages for the task-runner and the build process.

Next we need to install the client dependencies. Enter the following command:

bower install

#Testing ##Unit Test A very simple unit-testing is implemented (based on karma. The test only verifies some basis conditions.

Run the following command to execute the unit-tests:

gulp test

##Integration-tests Part of build task is the file "SpecRunner.html" generated. This HTML file contains all dependencies (e.g. mocha.js, chai.js, CrmFetchKit.bundle.js...) so the you need only to deploy this single HTML file as web-resource your environment. #Versions ##Version 3.x This version replaced jQuery dependency with bluebird. Due to the use of bluebird instead of jQuery, some method are no longer available by the returned promise:

always instead use finally
fail instead use catch

###Breaking Changes The optional async for Fetch, FetchMore and Assign is no longer supported. All methods are now async. That means that CrmFetchKit.Fetch(xml, false) will not perform a synchronous operation. To execute a sync operation use one of the *Sync methods (e.g. FetchSync, FetchMoreSync).

Furthermore supports the library now the methods GetById and GetByIdSync.

Note: Unfortunately depends CrmRestKit.js (use for the integration-tests) still jQuery. Therefor is it not possible to remove the jQuery dependency for now.

Internally uses CrmFetchKit now browserify for the dependency management.

##Version 2.x The version 2.x of the library uses Mocha.js as testing framework (instead of QUnit) and Gulp.js for the task automation (linting, build, minify, etc.)

###Breaking Changes

Before this version the getValue method returns an string for option-sets attributes. With the 2.x version, the method return a value of type number.
- See integration test should retrieve the optionset-value as "number"
The Assign method accepts now five attributes (id, entityname, assigneeId, assigneeEntityName, opt_async).

##Versions 1.x Previous versions (1.x) of this library are available on CodePlex (http://crmfetchkit.codeplex.com/)

casperj / crmfetchkit Goto Github PK

crmfetchkit's Introduction

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent