dynamicsnode/src/CRMClient.d.ts

Create simple scripts to interact with Dynamics CRM using Node.js

import { DataTable } from "./DataTable";
import { Guid } from "./Guid";
import { WhoAmIResponse } from "./Messages";
import { EntityMetadata } from "./CRMDataTypes";
export declare class CRMClient {
    connectionString: string;
    private _crmBridge;
    /**
     * Default constructor
     * @classdesc Allow access to CRM functions. Contains the functions to interact with CRM services.
     * @class CRMClient
     * @param {string} connectionString 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.
     * @see {@link https://msdn.microsoft.com/en-ie/library/mt608573.aspx} for further information
     *
     * @example <caption>config.json file format</caption>
     * {
     *      "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"
     *      }
     * }
     * @example <caption>Create a connection using a valid Connection String</caption>
     * var crm = new CRMClient("AuthType=Office365; Url=http://crm.contoso.com/xrmContoso; Domain=CONTOSO; Username=jsmith; Password=passcode");
     * @example <caption>Create a connection using the connection string named "connection2" specified in the config.json file</caption>
     * var crm = new CRMClient("connection2");
     * @example <caption>Create a connection using the connection string named "default" specified in the config.json file</caption>
     * var crm = new CRMClient();
     * @example <caption>Create a connection using the connection string named "default" specified in the config.json file</caption>
     * var crm = new CRMClient("default");
     */
    constructor(connectionString?: string, fakeBridge?: boolean);
    /**
     * Gets the bridge object between node and .net
     * @private
     * @method CRMClient#getBridge
     * @param fakeBridge {boolean} indicates if a fake bridge whants to be retrieved
     * @returns a .net bridge that allows node to interact with .net
     */
    private getBridge(fakeBridge);
    private tryGetModule(moduleId);
    private convert(propertiesArray);
    /**
    * Returns information about the current user. Useful for testing the active connection.
    * @returns a {@link WhoAmIResponse} object with the information about the authenticated user in CRM.
    * @method CRMClient#whoAmI
    * @example <caption>Returns information about the current user</caption>
    * 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
    */
    whoAmI(): WhoAmIResponse;
    /**
     * Tests the active connection. Throws an exception if there's any error.
     * The method performs a {@link WhoAmIRequest}.
     * @method CRMClient#testConnection
     * @see CRMClient#whoAmI
     */
    testConnection(): void;
    /**
     * Retrieves one single record from CRM.
     * @method CRMClient#retrieve
     * @param entityName {string} Name of the entity to be retrieved. The name is case insensitive, so all values are lowercased before being sent to CRM.
     * @param idOrConditions {string|Guid|object} Either a string with the GUID if the record to be retrieved, a {@link Guid} object with the same value, or a conditions object that returns only one record.
     * Learn how to write condition objects: {@link Fetch#setFilter}
     * @param attributes {string|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
     *
     * @returns A javascript object containing the values of the record. If no data found, then a null object is returned.
     *
     * @example <caption>Return all the columns for the specified account id</caption>
     * var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2");
     * console.log(account);
     * @example <caption>Return all the columns for the specified account id</caption>
     * var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2","*");
     * console.log(account);
     * @example <caption>Return all the columns for the specified account id</caption>
     * var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2",true);
     * console.log(account);
     * @example <caption>You can use the Guid class to specify the id parameter. This allows to perform a GUID format validation before calling the method.</caption>
     * var Guid = require("dynamicsnode").Guid;
     * var account = crm.retrieve("account",new Guid("6fefeb79-5447-e511-a5db-0050568a69e2"));
     * console.log(account);
     * @example <caption>Get the accountid,name,ownerid,createdon columns for the given account id</caption>
     * var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2",["accountid","name","ownerid","createdon"]);
     * console.log(account);
     * @example <caption>Get the name of the specified account</caption>
     * var account = crm.retrieve("account","6fefeb79-5447-e511-a5db-0050568a69e2","name");
     * console.log(account.name);
     * @example <caption>Accessing information about a related record</caption>
     * 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
     * @example <caption>Returns an account using a condition object. If there are more than one account named "Acme" then an exception will be thrown</caption>
     * var account = crm.retrieve("account",{name:"Acme"});
     * console.log(account.name);
     */
    retrieve(entityName: string, idOrConditions: string | Guid | Object, pColumns?: string | string[] | boolean): any;
    retrieveMultiple(fetchXml: string): DataTable;
    retrieveMultiple(entityName: string, conditions?: any, attributes?: boolean | string | string[]): DataTable;
    /** It is a simpified way of retrieving all the existing records of an entity. Is equivalent to call the {@link CRMClient#retrieveMultiple} method not specifying the conditions or attributes method
     * @method CRMClient#retrieveAll
     * @param entityName {string} Name of the entity which records you want to retrieve.
     * @returns {DataTable} {@link DataTable} object with the records found.
     * @example <caption>Retrieve all existing account records</caption>
     * var accounts = crm.retrieveAll("account");
    */
    retrieveAll(entityName: string): DataTable;
    /**
     * 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.
     * @method CRMClient#create
     * @param entityName {string} The name of the entity which record you want to create
     * @param attributes {object} Javascript object with the values the new record will have.
     *
     * @returns {string} GUID of the record created.
     */
    create(entity: string, attributes: Object): string;
    /**
     * 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.
     * @method CRMClient#create
     * @param entityName {string} The name of the entity which record you want to create
     * @param attributes {object} Javascript object with the values the new record will have.
     *
     * @returns {string} GUID of the record created.
     */
    create(data: DataTable): void;
    private createInternal(entityName, attributes);
    private ConvertToEntity(entityName, attributes);
    private ConvertToString(attributeName, attributeValue);
    private ConvertToPartyList(attributeValue, attributeMetadata);
    private ConvertToDate(attributeValue, attributeMetadata);
    private ConvertToBoolean(attributeValue, attributeMetadata);
    private ConvertToOptionset(attributeValue, attributeMetadata);
    private ConvertToEntityReference(attributeValue, attributeMetadata);
    /**
     * Deletes one on more records in CRM, and returns the number of records affected.
     * @method CRMClient#delete
     * @param entityName {string} Name of the entity which record you want to delete
     * @param idsOrConditions {string|Guid|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: {@link Fetch#setFilter}
     * @returns {number} Number of records deleted
     * @example <caption>Delete an account with a known Guid</caption>
     * var affectedRecords = crm.delete("account","6fefeb79-5447-e511-a5db-0050568a69e2");
     * @example <caption>Delete an account with a known Guid. A validation of the Guid format will be performed before calling to the method.</caption>
     * var affectedRecords = crm.delete("account",new Guid("6fefeb79-5447-e511-a5db-0050568a69e2"));
     * @example <caption>Delete several account records at once</caption>
     * var affectedRecords = crm.delete("account",["6fefeb79-5447-e511-a5db-0050568a69e2","6fefeb79-5447-e511-a5db-0050568a69e2");
     * @example <caption>Delete all existing accounts named "contoso"</caption>
     * var affectedRecords = crm.delete("account",{name:"contoso"});
     */
    delete(entityName: string, idsOrConditions: any): number;
    private deleteMultiple(entityName, ids);
    /**
     * Updates one or more records that meet the specified conditions and returns the number of updated records.
     * @method CRMClient#update
     * @param entityName {string} The name of the entity which record you want to update.
     * @param attributes {object} Javascript object with the values the new record will have.
     * @param 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: {@link Fetch#setFilter}
     * @returns {number} Number of modified records
     *
     * @example <caption>Updates all the accounts which name is contoso, and set the attribute value to "contoso-updated"</caption>
     * var affectedRecords = crm.update("account",{name:"contoso-updated"},{name:"contoso"})
     * @example <caption>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.</caption>
     * var affectedRecords = crm.update("account",{accountid:"6fefeb79-5447-e511-a5db-0050568a69e2",name:"contoso-updated"})
     */
    update(entityName: string, attributes: any, conditions?: any): number;
    getIdField(entityName: string): string;
    /** 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.
     * @method CRMClient#createOrUpdate
     * @param entityName {string} Name of the entity which record you want to update.
     * @param attributes {object} Javascript object with the attributes you want to create or update.
     * @param matchFields {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 {@link CRMClient#retrieve}.
     * @example <caption>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</caption>
     * crm.createOrUpdate("account",{name:"contoso", description:"Account Updated"},["name"]);
     * @example <caption>Searches for an account named "contoso" owned by me. If exists, it updates it, otherwhise it creates a new one.</caption>
     * var me = crm.whoAmI().UserId;
     * crm.createOrUpdate("account",{name:"contoso", description:"Account Updated", ownerid:me},["name","ownerid"]);
    */
    createOrUpdate(entityName: string, attributes: any, matchFields: string[]): void;
    /** For every record in the specified Table, tries to find out if it does exists, and if doesn't it creates it.
     * @method CRMClient#createIfDoesNotExist
     * @param data {DataTable} DataTable with the entity name and the records to create in CRM.
     * @param matchFields {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 {@link CRMClient#retrieve}.
     * @example <caption>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.</caption>
     * var accountsToLoad = DataTable.load("AccountsToLoad.xlsx");
     * crm.createIfDoesNotExist(accountsToLoad,["emailaddress1"]);
    */
    createIfDoesNotExist(data: DataTable, matchFields: string[]): void;
    /** 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.
     * @method CRMClient#createIfDoesNotExist
     * @param entityName {string} Name of the entity which record you want to create.
     * @param attributes {object} Javascript object with the attributes you want to create.
     * @param matchFields {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 {@link CRMClient#retrieve}.
     * @example <caption>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</caption>
     * crm.createIfDoesNotExist("account",{name:"contoso", description:"New Account Created", emailaddress1:"info@contoso.com"},["emailaddress1"]);
     * @example <caption>Searches for an account named "contoso" owned by me. If it doesn't exist, it creates it.</caption>
     * var me = crm.whoAmI().UserId;
     * crm.createIfDoesNotExist("account",{name:"contoso", description:"Account Updated", ownerid:me},["name","ownerid"]);
    */
    createIfDoesNotExist(entityName: string, attributes: Object, matchFields: string[]): void;
    private createUpdate(entityName, attributes, matchFields, update?);
    /** */
    associateData(data: DataTable): void;
    associate(fromEntityName: string, fromEntityId: string | Guid, relationshipName: string, toEntityName: string, toEntityId: string | Guid): void;
    disassociateData(data: DataTable): void;
    disassociate(fromEntityName: string, fromEntityId: string | Guid, relationshipName: string, toEntityName: string, toEntityId: string | Guid): void;
    /** Gets metadata information for a particular CRM Entity.
     * @method CRMClient#getEntityMetadata
     * @param entityName {string} Name of the entity which metadata information you want to get
     * @example <caption>Retrieve metadata information of the account entity</caption>
     * var metadata = crm.getEntityMetadata("account");
     */
    getEntityMetadata(entityName: string): EntityMetadata;
    Execute(request: any): any;
    assign(targetId: Guid | string, targetType: string, assigneeId: Guid | string, assigneeType?: string): void;
    export(entityName: string, fileName: string): void;
    import(fileName: string): void;
    /** Sets the state and status of a record.
     * @method CRMClient#setState
     * @param entityName {string} Name of the entity which state or status you want to set
     * @param entityId {Guid|string} GUID of the record which state or status you want to set
     * @param state {number|string} Name or Value of the State you want to set
     * @param status {number|string} Name or Value of the Status you want to set
     * @example <caption>Set the state of a task to Completed (1) and the Status to Completed (5)</caption>
     * crm.setState('task','6fefeb79-5447-e511-a5db-0050568a69e2',1,5);
     * @example <caption>Set the state of a task using the text values</caption>
     * crm.setState('task','6fefeb79-5447-e511-a5db-0050568a69e2','Completed','Completed');
     * */
    setState(entityName: string, entityId: Guid | string, state: number | string, status: number | string): void;
}