DynamicsNode

Class: CRMClient

CRMClient

Allow access to CRM functions. Contains the functions to interact with CRM services.

new CRMClient(connectionString)

Default constructor

Parameters:
Name Type Description
connectionString string

Optional. A valid connection string or connection string name.
The connection string can be either a valid connection string or a name of an existing connection string in the file "config.json" at the root path of your application.
If no value is passed to the constructor, the "default" text will be assumed, which means that a connection string named "default" will be used.
Source:
See:
Examples

config.json file format

{
     "connectionStrings":
     {
         "default":"AuthType=Office365; Url=http://crm.contoso.com/xrmContoso; Domain=CONTOSO; Username=jsmith; Password=passcode",
         "connection2":"AuthType=AD; Url=http://crm.contoso.com/xrmContoso"
     }
}

Create a connection using a valid Connection String

var crm = new CRMClient("AuthType=Office365; Url=http://crm.contoso.com/xrmContoso; Domain=CONTOSO; Username=jsmith; Password=passcode");

Create a connection using the connection string named "connection2" specified in the config.json file

var crm = new CRMClient("connection2");

Create a connection using the connection string named "default" specified in the config.json file

var crm = new CRMClient();

Create a connection using the connection string named "default" specified in the config.json file

var crm = new CRMClient("default");

Methods

create(entityName, attributes)

Creates a record in CRM. The names in the entity or attributes are case insensitive, so all the names will be lowercased before
send the operation to Crm.

Parameters:
Name Type Description
entityName string

The name of the entity which record you want to create
attributes object

Javascript object with the values the new record will have.
Source:
Returns:

GUID of the record created.

Type
string
Examples

Create an account named "Contoso"

var accountid = crm.create("account",{name:"contoso",description:"this is a test",AccountCategoryCode:1});
console.log(accountid);

Create an email with activity parties

var contact1Id = "{6633f95b-c146-45d4-ae99-6bd84f9bf7bc}"
var contact2Id = "{6633f95b-c146-45d4-ae99-6bd84f9bf7bc}"
var userId = "{6633f95b-c146-45d4-ae99-6bd84f9bf7bc}"
var email = {
              To : [{id:contact1Id,type:"contact"},{id:contact2Id,type:"contact"}],
              From : [{id:userId,type:"systemuser"}],
              Subject : "Test Email",
              Description : "Test Email",
              DirectionCode : true
             };
var emailId = crm.create("email",email);

create(data)

Creates records in CRM using the rows defined in the DataTable.
The id attribute of every created record will be updated with the generated CRM GUID.
You need to set the name of the table with the entity name that you want to create.

Parameters:
Name Type Description
data DataTable

DataTable with the data to be created in CRM.
Source:
Example

Create a set of accounts using an excel file

var accountsToLoad = DataTable.load("AccountsToLoad.xlsx");
crm.create(accountsToLoad);
console.log(accountsToLoad.rows[0].accountid); // This will output the GUID of the created record

createIfDoesNotExist(data, matchFields)

For every record in the specified Table, tries to find out if it does exists, and if doesn't it creates it.

Parameters:
Name Type Description
data DataTable

DataTable with the entity name and the records to create in CRM.
matchFields Array.<string>

List of fields in the attributes parameter you want to use to know if the record exists in CRM.
The attributes specified in this parameter will be used to perform a CRMClient#retrieve.
Source:
Example

Loads a list of accounts from an Excel file and creates only the ones that don't exist already in CRM. It uses the email address to know if the account exists or not.

var accountsToLoad = DataTable.load("AccountsToLoad.xlsx");
crm.createIfDoesNotExist(accountsToLoad,["emailaddress1"]);

createIfDoesNotExist(entityName, attributes, matchFields)

Takes a list of attributes and values, tries to find an existing record with those values in CRM, and if doesn't exists it creates it.

Parameters:
Name Type Description
entityName string

Name of the entity which record you want to create.
attributes object

Javascript object with the attributes you want to create.
matchFields Array.<string>

List of fields in the attributes parameter you want to use to know if the record exists in CRM.
The attributes specified in this parameter will be used to perform a CRMClient#retrieve.
Source:
Examples

Create an account named "contoso" only if it doesn't exist one already with the specified email. If theres more than one account with that email, an exception will be thrown

crm.createIfDoesNotExist("account",{name:"contoso", description:"New Account Created", emailaddress1:"info@contoso.com"},["emailaddress1"]);

Searches for an account named "contoso" owned by me. If it doesn't exist, it creates it.

var me = crm.whoAmI().UserId;
crm.createIfDoesNotExist("account",{name:"contoso", description:"Account Updated", ownerid:me},["name","ownerid"]);

createOrUpdate(entityName, attributes, matchFields)

Takes a list of attributes and values, tries to find an existing record with those values in CRM, if it exists,
then performs an update, otherwhise it creates it.

Parameters:
Name Type Description
entityName string

Name of the entity which record you want to update.
attributes object

Javascript object with the attributes you want to create or update.
matchFields Array.<string>

List of fields in the attributes parameter you want to use to know if the record exists in CRM.
The attributes specified in this parameter will be used to perform a CRMClient#retrieve.
Source:
Examples

Create an account named "contoso". In this case, a retrieve of an account with name="contoso" will be performed. If exists, then the name and description will be updated. If it doesn't exist, then the account will be created with the specified name and description. If theres more than one account with that name, an exception will be thrown

crm.createOrUpdate("account",{name:"contoso", description:"Account Updated"},["name"]);

Searches for an account named "contoso" owned by me. If exists, it updates it, otherwhise it creates a new one.

var me = crm.whoAmI().UserId;
crm.createOrUpdate("account",{name:"contoso", description:"Account Updated", ownerid:me},["name","ownerid"]);

delete(entityName, idsOrConditions)

Deletes one on more records in CRM, and returns the number of records affected.

Parameters:
Name Type Description
entityName string

Name of the entity which record you want to delete
idsOrConditions string | Guid | Array.<string> | object

Can be either a Guid, a string, an array or a conditions object.
If it is Guid will delete the record with the specified id.
If it is a string, must be a Guid value, and again, will delete the records matching the specified id.
If the parameter is an array, each element in it must be either a string or a Guid, and in each case, the records deleted will be the ones specified by these Guids.
If it is a condition object, first, all the matching records will be retrieved, and then deleted.
Learn how to write condition objects: Fetch#setFilter
Source:
Returns:

Number of records deleted

Type
number
Examples

Delete an account with a known Guid

var affectedRecords = crm.delete("account","6fefeb79-5447-e511-a5db-0050568a69e2");

Delete an account with a known Guid. A validation of the Guid format will be performed before calling to the method.

var affectedRecords = crm.delete("account",new Guid("6fefeb79-5447-e511-a5db-0050568a69e2"));

Delete several account records at once

var affectedRecords = crm.delete("account",["6fefeb79-5447-e511-a5db-0050568a69e2","6fefeb79-5447-e511-a5db-0050568a69e2");

Delete all existing accounts named "contoso"

var affectedRecords = crm.delete("account",{name:"contoso"});

<private> getBridge(fakeBridge)

Gets the bridge object between node and .net

Parameters:
Name Type Description
fakeBridge boolean

indicates if a fake bridge whants to be retrieved
Source:
Returns:

a .net bridge that allows node to interact with .net

getEntityMetadata(entityName)

Gets metadata information for a particular CRM Entity.

Parameters:
Name Type Description
entityName string

Name of the entity which metadata information you want to get
Source:
Example

Retrieve metadata information of the account entity

var metadata = crm.getEntityMetadata("account");

retrieve(entityName, idOrConditions, attributes)

Retrieves one single record from CRM.

Parameters:
Name Type Description
entityName string

Name of the entity to be retrieved. The name is case insensitive, so all values are lowercased before being sent to CRM.
idOrConditions string | Guid | object

Either a string with the GUID if the record to be retrieved, a Guid object with the same value, or a conditions object that returns only one record.
Learn how to write condition objects: Fetch#setFilter
attributes string | Array.<string> | boolean

Optional. Either an attribute name, an array of attributes, or a true value indicating that all attributes must be retrieved. The default value is true. An * value has the same effect
Source:
Returns:

A javascript object containing the values of the record. If no data found, then a null object is returned.

Examples

Return all the columns for the specified account id

var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2");
console.log(account);

Return all the columns for the specified account id

var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2","*");
console.log(account);

Return all the columns for the specified account id

var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2",true);
console.log(account);

You can use the Guid class to specify the id parameter. This allows to perform a GUID format validation before calling the method.

var Guid = require("dynamicsnode").Guid;
var account = crm.retrieve("account",new Guid("6fefeb79-5447-e511-a5db-0050568a69e2"));
console.log(account);

Get the accountid,name,ownerid,createdon columns for the given account id

var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2",["accountid","name","ownerid","createdon"]);
console.log(account);

Get the name of the specified account

var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2","name");
console.log(account.name);

Accessing information about a related record

var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2","ownerid");
console.log(account.ownerid); // outputs the GUID value
console.log(account.ownerid_type); // outputs systemuser
console.log(account.ownerid_name); // outputs John Doe

Returns an account using a condition object. If there are more than one account named "Acme" then an exception will be thrown

var account = crm.retrieve("account",{name:"Acme"});
console.log(account.name);

retrieveAll(entityName)

It is a simpified way of retrieving all the existing records of an entity. Is equivalent to call the CRMClient#retrieveMultiple method not specifying the conditions or attributes method

Parameters:
Name Type Description
entityName string

Name of the entity which records you want to retrieve.
Source:
Returns:

DataTable object with the records found.

Type
DataTable
Example

Retrieve all existing account records

var accounts = crm.retrieveAll("account");

retrieveMultiple(entityNameOrFetchXml, conditions, attributes)

Retrieves one or more records of the specified entity that fulfill the specified conditions.

Parameters:
Name Type Description
entityNameOrFetchXml string

Name of the entity or Fetch Xml query to specify the records to be retrieved. More info: https://msdn.microsoft.com/en-us/library/gg328332.aspx
conditions object

Optional. In case you don't want to write a FetchXml to specify the records to retrieve, you can use a conditions object to specify the criteria to retrieve records. If you omit this parameter, all the existing records of the specified entity will be retrieved; omitting this parameter is equivalent to write a FetchXml without any filter conditions.
Learn how to write condition objects: Fetch#setFilter
attributes string | Array.<string> | boolean

Optional. Either an attribute name, an array of attributes, or a true value indicating that all attributes must be retrieved. The default value is true. An * value has the same effect
Source:
See:
Returns:

DataTable object with the records found.

Type
DataTable
Examples

Retrieves all the records of the account entity. Only the accountid column will be retrieved (the id column is always returned in all Crm queries)

var accounts = crm.retrieveMultiple("<fetch><entity name='account'></entity></fetch>");

Retrieves all the records of the account entity. Includes also all the columns of the entity.

var accounts = crm.retrieveMultiple("account");

Retrieves all the records of the account entity where the account name is equals to "contoso". Returns all the columns of the entity.

var accounts = crm.retrieveMultiple("account",{name:"contoso"});

Retrieves all the records of the account entity where the account name is equals to "contoso", but only the specified columns are included in the query.

var accounts = crm.retrieveMultiple("account",{name:"contoso"},["accountid","name","ownerid","createdon"]);

Retrieves all the records of the account entity where the account name is equals to "contoso" or "acme". Returns all the columns of the entity.

var accounts = crm.retrieveMultiple("account",{name:["contoso","acme"]});

setState(entityName, entityId, state, status)

Sets the state and status of a record.

Parameters:
Name Type Description
entityName string

Name of the entity which state or status you want to set
entityId Guid | string

GUID of the record which state or status you want to set
state number | string

Name or Value of the State you want to set
status number | string

Name or Value of the Status you want to set
Source:
Examples

Set the state of a task to Completed (1) and the Status to Completed (5)

crm.setState('task','6fefeb79-5447-e511-a5db-0050568a69e2',1,5);

Set the state of a task using the text values

crm.setState('task','6fefeb79-5447-e511-a5db-0050568a69e2','Completed','Completed');

testConnection()

Tests the active connection. Throws an exception if there's any error.
The method performs a WhoAmIRequest.

Source:
See:

update(entityName, attributes, conditions)

Updates one or more records that meet the specified conditions and returns the number of updated records.

Parameters:
Name Type Description
entityName string

The name of the entity which record you want to update.
attributes object

Javascript object with the values the new record will have.
conditions opbject

Optional. Javascript condition object with the filter values that is going to be used to know which records are going to be updated.
If you omit this parameter, then you have to provide the record GUID in the attributes parameter.
Learn how to write condition objects: Fetch#setFilter
Source:
Returns:

Number of modified records

Type
number
Examples

Updates all the accounts which name is contoso, and set the attribute value to "contoso-updated"

var affectedRecords = crm.update("account",{name:"contoso-updated"},{name:"contoso"})

In this example, only the account with the specified account id will be updated. If the specified record id exists, then affectedRecords will be equals to 1.

var affectedRecords = crm.update("account",{accountid:"6fefeb79-5447-e511-a5db-0050568a69e2",name:"contoso-updated"})

whoAmI()

Returns information about the current user. Useful for testing the active connection.

Source:
Returns:

a WhoAmIResponse object with the information about the authenticated user in CRM.

Example

Returns information about the current user

var who = crm.whoAmI();
console.log(who.BusinessUnitId); // prints 6fefeb79-5447-e511-a5db-0050568a69e2
console.log(who.OrganizationId); // prints 2b476bd1-aaed-43ee-b386-eee0f1b87207
console.log(who.UserId); // prints 9ba35c25-b892-4f8a-b124-3920d9873af4