CSharp API

From RangerMSP Wiki - PSA software for MSPs and IT services providers
Jump to: navigation, search

Disclaimer

This documentation refers to RangerMSP 5.6 or later version and assumes RangerMSP is installed and accessible on the local computer.

Introduction

This document demonstrates how to use the RangerMSP C# API library in order to programmatically connect to your RangerMSP server and query or manipulate the RangerMSP database.c


System Requirements

  • RangerMSP 5.6 or later.
  • Visual C# .NET 2008 or Visual C# .NET 2010.
  • CRMLib.dll (the RangerMSP C# compiled library).

Getting Started

Libraries Setup

To download, compile and setup the libraries, please refer to CSharp API Library Setup.

Start Basic Program

After you create your C# project, you'll need to add a reference to the CRMLib.dll file, in order to have access to the RangerMSP library classes.

Each application using the library will have to initialize on startup the CRM.Application object and terminate it on exit. Initialization method requires that you pass an object instance of CRM.Config class.

Connecting to the RangerMSP database can be done in two ways:

  1. Using a Local Server - run your program on the same server where the RangerMSP Server runs.
  2. Using Web API - run your program anywhere and connect to a remote RangerMSP server over Web services interface.

Connection parameters vary between these options. See the variations below:

Local Server

For connections to a local RangerMSP server configure the following settings:

  • AppName
This is free text, preferably the name of your application.
  • DllFolder
Behind the scenes the library uses the two RangerMSP API dlls: CmtDbEng.dll and CmtDbQry.dll.
In the default RangerMSP installation you'll find these files in 'C:\\RangerMSP\\ThirdParty\\UserDev'.
Important Note: Always point to this folder and do not copy the dll files elsewhere. This is because when the RangerMSP version upgrade runs it also upgrades the dll files stored in this folder. This verifies that you will always be using the latest release.
  • DbFolder
Path to the RangerMSP database, default is 'C:\\RangerMSP\\db'.

Assuming these default values, we can configure the CRM.Config object like this: 

CRM.Config config = new CRM.Config();
config.AppName = "C# Demo";
config.DllFolder = "C:\\RangerMSP\\ThirdParty\\UserDev";
config.DbFolder = "C:\\RangerMSP\\db";

You should of course ensure these paths are correct on your disk and modify the values accordingly.

Remote Server (Web API)

To connect to a remote RangerMSP server with the Web API, configure the following settings:

  • AppName
This is free text, preferably the name of your application.
  • WebAPIUrl
Url to the RangerMSP server running the Web API, either local or remote.
Url must include the http:// or https:// prefix, otherwise the API will not be able to connect.
Valid examples include http://localhost:4964/ and https://webapi.myRangerMSPserver.com/.
  • Password
Your authorization password/token
  • UseWebAPI
Boolean value, must be set to true to use the Web API

Assuming these default values, we can configure the CRM.Config object like this: 

CRM.Config config = new CRM.Config();
config.AppName = "C# Demo";
config.WebAPIUrl = "http://localhost:4964/";
config.Password = "yourpassword";
config.UseWebAPI = true;

Initialization

The configuration settings explained above are the only differences between connecting to a local RangerMSP server or remote RangerMSP server running the Web API.

Now we can initialize the CRM.Application object with these settings: 

//CRM.Application.Initialize must be the first call before invoking any other RangerMSP library method
//and it should be done only once in the program's lifetime.
CRM.Application.Initialize(config);

If anything goes wrong, the above line will throw an exception of the CRM.Exception class. To prevent unexpected termination of the program execution, we recommend having any call to the RangerMSP library enclosed in a try/catch block.

Before exit, we terminate the CRM.Application object: 

//Before exit we should call CRM.Application.Terminate to gracefully release all application resources
//and this should be done only once in the program's lifetime.
CRM.Application.Terminate();

The most basic C# application that just connects to RangerMSP and terminates could look something like this: 

try
{
    CRM.Config config = new CRM.Config();
    config.AppName = "C# Demo";
    config.DllFolder = "C:\\RangerMSP\\ThirdParty\\UserDev";
    config.DbFolder = "C:\\RangerMSP\\db";

    CRM.Application.Initialize(config);

    //At this point we have successfully initialized the CRM.Application
    //and can start using the other library classes
}
catch (CRM.Exception exc)
{
    Console.Out.Write(exc.Message);
}
finally
{
    CRM.Application.Terminate();
}

Now that we have confirmed the connectivity to the RangerMSP server (if the above code successfully runs), we can continue adding more functionality to the example.

The library exposes as C# classes the same RangerMSP objects (Account, Ticket etc.) available through the native RangerMSP API and you can refer to the API Reference Manual for database fields reference.


With any of these objects you can:

  • Search and query for objects with CRM.ObjectQuery that satisfy certain criteria.
  • Read and display the properties of the retrieved objects.
  • Update and save the properties of the retrieved objects.
  • Create and save new objects.


Now let's see how we can search for CRM.Account objects. We instantiate an object of the CRM.ObjectQuery class and pass CRM.Account class as generics parameter. 

CRM.ObjectQuery<CRM.Account> accountSearch = new CRM.ObjectQuery<CRM.Account>();

CRM.ObjectQuery class can accept any of the RangerMSP objects in this parameter, but we want to search for accounts now.

Next, we need to set criteria (or more than one) we want to search for: 

accountSearch.AddCriteria(CRM.Account.Fields.City, CRM.OperatorEnum.opEqual, "New York");

Тhe first parameter to the AddCriteria method is either a static object instance of CRM.CrmField class representing the field we want to look in or the internal API field name. Refer to the API Field Name column in the Account Class table for a complete list of the available fields for the CRM.Account class.

The second parameter is a compare operator. We here use the CRM.OperatorEnum.opEqual to get only exact matches. In order to get a broader match in the results you can use CRM.OperatorEnum.opLike operator.

The third parameter is the value we want to find. Prepending and/or appending % (percent) sign at the beginning and/or at the end while using CRM.OperatorEnum.opLike operator, will match the phrase even if in the middle of a sentence.

Now we can execute the search and retrieve the CRM.Account objects (if any): 

List<CRM.Account> accounts = accountSearch.FetchObjects();

The above line will populate the List (System.Collections.Generic.List) with all CRM.Account objects that were found. Now we can use foreach statement to iterate through the accounts: 

foreach (CRM.Account account in accounts)
{
    Console.Out.WriteLine(account.CompanyName);
}

Or we can manipulate these accounts: 

foreach (CRM.Account account in accounts)
{
    if (account.Zip.Length == 0)
    {
        account.Zip = "10001";
        account.Save();
    }
}


We invoke the CRM.Account's Save method on both new or existing accounts. For a new account, invoking the Save method would insert a new account in the RangerMSP database. For an existing account, invoking the Save method would update the fields we modified in the existing account. This rule applies to all RangerMSP objects.

Another option is to add a new ticket for each of the accounts: 

foreach (CRM.Account account in accounts)
{
    CRM.Ticket ticket = new CRM.Ticket();
    ticket.AccountREC_ID = account.AccountREC_ID;
    ticket.Description = "Sample ticket for a NewYork account";
    ticket.Save();
}

GetFieldValue and SetFieldValue methods

Each of the RangerMSP library objects have a set of properties that are exposed as C# properties that you can directly manipulate or read from. You already saw few examples of these properties in the above examples, as: account.Zip or ticket.Description. This is the preferred and more intuitive way of accessing the RangerMSP fields.


However, there is also another way of achieving the same results, by invoking GetFieldValue and SetFieldValue and specifying the internal field name. These methods should only be used if necessary, for example, when updating user-defined custom fields which are not part of the class predefined basic fields.

Here is an equivalent of the above example that uses these two generic methods, instead of the object's properties: 

foreach (CRM.Account account in accounts)
{
    CRM.Ticket ticket = new CRM.Ticket();
    ticket.SetFieldValue("FLDTKTCARDID", account.GetFieldValue("FLDCRDRECID"));
    ticket.SetFieldValue("FLDTKTPROBLEM", "Sample ticket for a NewYork account");
    ticket.Save();
}

All internal field names are listed in Classes and Objects below.

Exception Handling

While working with the RangerMSP C# library, some operations can fail. In this case the library will throw an exception of the CRM.Exception class. We recommend enclosing all calls to the RangerMSP library in a try/catch block.

To find out more about the exact error that ocured when an exception is thrown, you can inspect the CRM.Exception.Status property that holds the last RangerMSP Status value, or inspect the list of CRM.Exception.Codes (if any). Please refer to Error Codes Description for the description of these values.

Complete Program Sample

using System;
using System.Collections.Generic;
using System.Text;

namespace RangerMSP_CSharp
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                CRM.Config config = new CRM.Config();
                config.AppName = "C# Demo";
                config.DllFolder = "C:\\RangerMSP\\ThirdParty\\UserDev";
                config.DbFolder = "C:\\RangerMSP\\db";

                CRM.Application.Initialize(config);

                //At this point we have successfully initialized the CRM.Application
                //and can start using the other library classes

                CRM.ObjectQuery<CRM.Account> accountSearch = new CRM.ObjectQuery<CRM.Account>();
                accountSearch.AddCriteria(CRM.Account.Fields.City, CRM.OperatorEnum.opEqual, "New York");
                List<CRM.Account> accounts = accountSearch.FetchObjects();

                foreach (CRM.Account account in accounts)
                {
                    Console.Out.WriteLine(account.CompanyName);
                }
            }
            catch (CRM.Exception exc)
            {
               //here we catch RangerMSP specific error
               //we can inspect the RangerMSP status (exc.Status) 
               //exc.Codes contains all error codes last call generated

               //here we show the error message
                Console.Out.Write(exc.Message);
            }
            catch (Exception exc)
            {
                Console.Out.Write(exc.Message);
            }
            finally
            {
                CRM.Application.Terminate();
            }
        }
    }
}

Classes and Objects

The RangerMSP C# API provides easy access to all objects using a class for each entity in the system (such as Account, Ticket, Asset, etc.).

All classes include:

  1. API functions and routines (which are derived from the base CRM.Object class).
  2. Class data fields, providing an easy way to update the object's data.


All RangerMSP's objects should be updated by setting the class data fields (properties) and then calling the Save method. For example, to create a new account programmatically (assuming CRM.Application was initialized successfully), one would use the following code snippet: 

CRM.Account account = new CRM.Account();
account.FileAs = "ACME Company";
account.Dear = "Mr.";
account.Contact = "John Doe";
account.Save();


Another option is using SetFieldData and GetFieldData as mentioned earlier, which provide low-level access to data fields. This option should only be used if necessary, for example, when updating user-defined fields which are not part of the class basic fields.


Object Class

The CRM.Object class is the base class for all RangerMSP accessible objects (as Ticket, Account, Asset, etc.). The public methods exposed by the CRM.Object class are available to the derived classes.

Object Method Reference Table

Access modifier Return value Method Arguments Description
public void SetFieldValue (string sKey, string sValue) Assigns the value (sValue) of the field passed in sKey argument. Save must be called for the change to take effect. Use this method to access user-defined custom fields.
public string GetFieldValue (string sKey) Retrieves the value of the field passed in sKey argument. Use this method to access user-defined custom fields.
public void Reload () Reloads the Object values from the database. The value of the object unique identifier (REC_ID, the exact name depends on the concrete derived object class)
public void Reinit (string sID) Same as Reload except the unique identifier is passed as argument.
public void Save () Saves all modified properties of the object to the database.

Object derived classes

Classes explained in this section are derived from CRM.Object class and map directly to a native RangerMSP object (Account, Ticket, etc.).

Account Class

The CRM.Account class derives from CRM.Object and encapsulates the Account Fields. The following table lists all exposed CRM.Account properties.

Account Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string AccountREC_ID FLDCRDRECID 20
public string AccountManager FLDCRDASSIGNCARDID 20
public string CompanyName FLDCRDCOMPANY 60
public string Contact FLDCRDCONTACT 40
public string Status FLDCRDSUBCONTSTATUS 1
public string Assistant FLDCRDASSISTANT 20
public string ContractREC_ID FLDCRDBCRECID 20
public string AccountNumber FLDCRDCARDID2 15
public string ID FLDCRDCARDID3 15
public string PopupMessage FLDCRDCARDMESSAGE Unlimited
public string AddressLine1 FLDCRDADDRESS1 40
public string AddressLine2 FLDCRDADDRESS2 40
public string AddressLine3 FLDCRDADDRESS3 40
public string City FLDCRDCITY 30
public string Country FLDCRDCOUNTRY 20
public string State FLDCRDSTATE 30
public string Zip FLDCRDZIP 15
public DateTime CreationDate FLDCRDCREATEDATE N/A
public string CreatedByUser FLDCRDCREATEUSERID 20
public string Dear FLDCRDDEAR 20
public string Department FLDCRDDEPARTMENT 35
public string DocumentsStoreDirectory FLDCRDDOCSFOLDER 100
public string EmailAddress1 FLDCRDEMAIL1 70
public string EmailAddress2 FLDCRDEMAIL2 70
public int AccountType FLDCRDENTITYKIND N/A
public string FaxNumber FLDCRDFAX1 25
public string FaxNumberExt FLDCRDFAXDESC1 15
public string FileAs FLDCRDFULLNAME 60
public string Type FLDCRDKIND 30
public string LastName FLDCRDLASTNAME 20
public string Notes FLDCRDNOTES Unlimited
public string Field FLDCRDPERSONID 20
public string Phone1Ext FLDCRDPHNDESC1 40
public string Phone2Ext FLDCRDPHNDESC2 40
public string Phone3Ext FLDCRDPHNDESC3 15
public string Phone4Ext FLDCRDPHNDESC4 15
public string Phone1 FLDCRDPHONE1 25
public string Phone2 FLDCRDPHONE2 25
public string Phone3 FLDCRDPHONE3 25
public string Phone4 FLDCRDPHONE4 25
public string Region FLDCRDREGIONCODE 15
public string PopupMessageDisplayIndication FLDCRDSHOWMESSAGE 1
public string SubContractCode FLDCRDSUBCODE 15
public string Salutation FLDCRDSUFFIX 20
public string Tax1 FLDCRDTAXCODE1 3
public string Tax2 FLDCRDTAXCODE2 3
public string Title FLDCRDTITLE 30
public string LastUpdatedBy FLDCRDUPDATEUSERID 20
public string WebAddress1 FLDCRDURL1 100
public string WebAddress2 FLDCRDURL2 100
public string Status FLDCRDUSER1 30
public string Field1 FLDCRDUSER2 30
public string Field2 FLDCRDUSER3 30
public string Field3 FLDCRDUSER4 30
public string Field4 FLDCRDUSER5 30

Ticket Class

The CRM.Ticket class derives from CRM.Object and encapsulates the Ticket Fields. The following table lists all exposed CRM.Ticket properties.

Ticket Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string TicketREC_ID FLDTKTRECID 20
public string AccountREC_ID FLDTKTCARDID 20
public string AssetREC_ID FLDTKTASSETRECID 20
public string ContactREC_ID FLDTKTCONTACTID 20
public string ContractREC_ID FLDTKTBCRECID 20
public string EmployeeREC_ID FLDTKTWORKERID 20
public int TicketPriority FLDTKTPRIORITY N/A
public string TicketNumber FLDTKTTICKETNO 20
public string Description FLDTKTPROBLEM Unlimited
public string TicketType FLDTKTKIND 25
public string Source FLDTKTSOURCE 30
public int EstimatedDurationTime FLDTKTSCHEDLENESTIM N/A
public string ShowTicketInDispatcher FLDTKTFORDISPATCH 1
public int Status FLDTKTSTATUS N/A
public string CreatedByUser FLDTKTCREATEUSER 20
public DateTime DueDate FLDTKTDUEDATETIME N/A
public string Resolution FLDTKTSOLUTION Unlimited
public DateTime UpdateDate FLDTKTUPDATEDATE N/A

Asset Class

The CRM.Asset class derives from CRM.Object and encapsulates the Asset Fields. The following table lists all exposed CRM.Asset properties.

Asset Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string AssetREC_ID FLDASTRECID 20
public string AssetCode FLDASTASSETCODE 30
public string AssetType FLDASTASSETTYPE 1
public string AssetName FLDASTNAME 60
public string Status FLDASTSTATUS 1
public string SerialNo FLDASTSERIALNO 30
public string AccountREC_ID FLDASTACCRECID 20
public string ContactREC_ID FLDASTCONTACTRECID 20
public string CreatedByUser FLDASTCREATEUSER 20
public DateTime PurchaseDate FLDASTCUSTPURDATE N/A
public string PurchasedFromUs FLDASTCUSTPURFROMUS 1
public string PurchaseInvoice FLDASTCUSTPUROURINV 15
public string CustomerPO FLDASTCUSTPURPO 15
public double PurchasePrice FLDASTCUSTPURPRICE N/A
public DateTime DeliveredDate FLDASTDELIVEDATE N/A
public string Description FLDASTDESC Unlimited
public string InstalledBy FLDASTINSTALBY 20
public DateTime InstalledDate FLDASTINSTALDATE N/A
public string LicenseCodes FLDASTLICENSECODE Unlimited
public string LicenseKeys FLDASTLICENSEKEYS Unlimited
public string LicenseNotes FLDASTLICENSENOTES Unlimited
public string Location FLDASTLOCATION 50
public string Manufacturer FLDASTMANUFACTURER 40
public string MnfSerialNo FLDASTMNFSERIALNO 30
public string Model FLDASTMODEL 20
public string Notes FLDASTNOTES Unlimited
public double Quantity FLDASTQUANTITY N/A
public string LastUpdateBy FLDASTUPDATEUSER 20
public string Field1 FLDASTUSER1 25
public string Field2 FLDASTUSER2 25
public string Field3 FLDASTUSER3 25
public string Field4 FLDASTUSER4 25
public string Field5 FLDASTUSER5 25
public DateTime Date1 FLDASTUSERDATE1 N/A
public double Number1 FLDASTUSERNUMBER1 N/A
public DateTime VendorPurchasedDate FLDASTVENDORDATEPURC N/A
public string VendorInvoice FLDASTVENDORINVNO 15
public string VendorPO FLDASTVENDOROURPO 15
public double VendorPrice FLDASTVENDORPRICE N/A
public string Vendor FLDASTVENDORRECID 20
public string VendorSerialNo FLDASTVENDORSERNO 30
public DateTime VendorWarrantyExpDate FLDASTVENDORWARREXP N/A
public string Version FLDASTVERSION 15
public DateTime WarrantyLicenseExp FLDASTWARREXPDATE N/A

Calendar Class

The CRM.Calendar class derives from CRM.Object and encapsulates the Calendar Fields of event type Appointment. The following table lists all exposed CRM.Calendar properties.

Calendar Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string CalendarREC_ID FLDEVTRECID 20
public int EventType FLDEVTWRITETOID N/A
public string EmployeeREC_ID FLDEVTWORKERID 20
public string PrivateUser FLDEVTPRIVATEID 20
public string AccountREC_ID FLDEVTCARDID 20
public string ContactREC_ID FLDEVTCONTACTID 20
public string DocumentREC_ID FLDEVTDOCID 20
public bool DoneIndication FLDEVTDONE N/A
public DateTime Date FLDEVTEVENTDATE N/A
public string Description FLDEVTFREETEXT Unlimited
public string TimeStart FLDEVTFROMTIME N/A
public string TimeEnd FLDEVTTOTIME N/A
public string RelLinkREC_ID FLDEVTLINKRECID 20
public string Field1 FLDEVTFAMILY 50
public string Field2 FLDEVTACTION 50
public string Field3 FLDEVTPLACE 40
public string Field4 FLDEVTPLACE1 30
public string Field5 FLDEVTPLACE2 30
public string CreatedByUser FLDEVTCREATEUSERID 20
public string LastUpdateByUser FLDEVTUPDATEUSER 20

Task Class

The CRM.Task class derives from CRM.Object and encapsulates the Calendar Fields of event type Task. The following table lists all exposed CRM.Task properties.

Task Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string TaskREC_ID FLDEVTRECID 20
public int EventType FLDEVTWRITETOID N/A
public string EmployeeREC_ID FLDEVTWORKERID 20
public string PrivateUser FLDEVTPRIVATEID 20
public string AccountREC_ID FLDEVTCARDID 20
public string ContactREC_ID FLDEVTCONTACTID 20
public string DocumentREC_ID FLDEVTDOCID 20
public bool DoneIndication FLDEVTDONE N/A
public DateTime Date FLDEVTEVENTDATE N/A
public string Description FLDEVTFREETEXT Unlimited
public string TimeStart FLDEVTFROMTIME N/A
public string RelLinkREC_ID FLDEVTLINKRECID 20
public string Field1 FLDEVTFAMILY 50
public string Field2 FLDEVTACTION 50
public string Field3 FLDEVTPLACE 40
public string Field4 FLDEVTPLACE1 30
public string Field5 FLDEVTPLACE2 30
public string CreatedByUser FLDEVTCREATEUSERID 20
public string LastUpdateByUser FLDEVTUPDATEUSER 20

Charge Class

The CRM.Charge class derives from CRM.Object and encapsulates the Charge Fields. The following table lists all exposed CRM.Charge properties.

Charge Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string ChargeREC_ID FLDSLPRECID 20
public string AccountREC_ID FLDSLPCARDID 20
public string EmployeeREC_ID FLDSLPWORKERID 20
public string ChargedItem FLDSLPITEMID 20
public string ContractREC_ID FLDSLPBCRECID 20
public string TicketREC_ID FLDSLPTICKETID 20
public DateTime [Date] FLDSLPSLIPDATE N/A
public string Description FLDSLPDESC Unlimited
public double Units_Hours FLDSLPQUANTITY N/A
public bool HourlyBased FLDSLPITEMUNITISHOUR N/A
public double AdjustAmount FLDSLPADJUSTAMOUNT N/A
public double AdjustPercent FLDSLPADJUSTPERCENT N/A
public string AdjustType FLDSLPADJUSTTYPE 1
public string FromTime FLDSLPSTARTTIME N/A
public string ToTime FLDSLPENDTIME N/A
public double Price_Rate FLDSLPPRICE N/A
public string Billable FLDSLPBILLKIND 1
public string Billed FLDSLPSTAGE 1
public string Field1 FLDSLPUSER1 25
public string CreateUser FLDSLPCREATEUSER 20

Quote Class

The CRM.Quote class derives from CRM.Object. The following table lists all exposed CRM.Quote properties.

Quote Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string QuoteREC_ID FLDQTERECID 20
public string AccountREC_ID FLDQTEACCOUNTRECID 20
public string Status FLDQTESTATUS 1
public string BillToAddress FLDQTEBILLTOADDRESS Unlimited
public string BillToContactREC_ID FLDQTECONTACTRECID 20
public DateTime QuoteDate FLDQTEQUOTEDATE N/A
public string ShipToContactREC_ID FLDQTESHIPTOCONTACT 20
public string ShipToAddress FLDQTESHIPTOADDRESS Unlimited
public string ContractREC_ID FLDQTEBCRECID 20
public string HeaderNotes FLDQTEHEADERNOTES Unlimited
public string FooterNotes FLDQTEFOOTERNOTES Unlimited
public double TotalAfterTax FLDQTETOTALAFTERTAX N/A
public double TotalTax1 FLDQTETOTALTAX1 N/A
public double TotalTax2 FLDQTETOTALTAX2 N/A
public double Tax1 FLDQTETAX1 N/A
public double Tax2 FLDQTETAX2 N/A
public double TotalAfterDiscount FLDQTETOTALAFTERDISC N/A
public double Discount FLDQTEDISCOUNT N/A
public double TotalForCustomer FLDQTETOTAL4CUSTOMER N/A
public bool IsPublic FLDQTEISPUBLIC N/A
public string Audit FLDQTEAUDIT Unlimited
public int QuoteNumber FLDQTEQUOTENO N/A
public string QuoteName FLDQTEQUOTENAME 100
public string QuoteReference FLDQTEREFERENCE 20
public string ManagerRec_ID FLDQTEWORKERID 20
public string QuoteUserField1 FLDQTEUSER1 30
public string QuoteUserField2 FLDQTEUSER2 30
public string QuoteUserField3 FLDQTEUSER3 30
public string QuoteNotes FLDQTENOTES Unlimited
public string WonConvertedTo FLDQTEWONCONVERTEDTO 1
public string SignatureEmail FLDQTECAFREEEMAIL 100
public string SignatureName FLDQTECAFREENAME 50
public string SignatureText FLDQTECAFREESIGNATRE 30
public string SignatureIPAddress FLDQTECAIPADDRESS 15
public DateTime SignatureDateAndTime FLDQTECATIMESTAMP N/A
public string SignatureWebUserName FLDQTECAWEBUSERNAME 70
public string SignatureWebUserREC_ID FLDQTECAWEBUSERRECID 20
public string CreatedByUser FLDQTECREATEUSER 20
public string LastUpdateByUser FLDQTEUPDATEUSER 20
public DateTime CreatedDate FLDQTECREATEDATE N/A
public DateTime UpdateDate FLDQTEUPDATEDATE N/A

QuoteLine Class

The CRM.QuoteLine class derives from CRM.Object. The following table lists all exposed CRM.QuoteLine properties.

QuoteLine Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string QuoteLineREC_ID FLDQTLRECID 20
public string QuoteREC_ID FLDQTLQUOTERECID 20
public string ItemREC_ID FLDQTLITEMRECID 20
public string ItemGroup FLDQTLITEMTYPEGROUP 1
public double Quantity FLDQTLQUANTITY N/A
public double Price FLDQTLPRICE N/A
public string DiscountMarkup FLDQTLADJUST 1
public double DiscountTotalAmountForCustomer FLDQTLADJAMTDIS4CUST N/A
public double DiscountPercentageForCustomer FLDQTLADJPERDIS4CUST N/A
public double LineTotal FLDQTLBILLTOTAL N/A
public double LineTotalForCustomer FLDQTLTOTAL4CUSTOMER N/A
public string LineType FLDQTLLINETYPE 1
public int LineSortOrder FLDQTLORDER N/A
public double PriceForCustomerAfterMarkup FLDQTLPRICE4CUSTOMER N/A
public double AdjustAmount FLDQTLADJUSTAMOUNT N/A
public double AdjustPercent FLDQTLADJUSTPERCENT N/A
public string AdjustType FLDQTLADJUSTTYPE 1
public string Description FLDQTLDESCRIPTION Unlimited
public string CreatedByUser FLDQTLCREATEUSER 20
public string LastUpdateByUser FLDQTLUPDATEUSER 20
public DateTime CreatedDate FLDQTLCREATEDATE N/A
public DateTime UpdateDate FLDQTLUPDATEDATE N/A

QuoteLine Helper Methods

Besides the get/set properties, QuoteLine supports number of helper methods.

QuoteLine Helper Methods Table

Access modifier Return value Property Arguments Description
public void SetQuoteLineItem (string sItemREC_ID, double dblQuantity, double dblPrice) Fills the appropriate fields for inserting Item type QuoteLine.
public void SetQuoteLineItemWithDiscount (string sItemREC_ID, double dblQuantity, double dblPrice, double dblDiscount, bool bByPercent) Fills the appropriate fields for inserting Item type QuoteLine specifying a discount.
public void SetQuoteLineItemWithMarkup (string sItemREC_ID, double dblQuantity, double dblPrice, double dblMarkup, bool bByPercent) Fills the appropriate fields for inserting Item type QuoteLine specifying a markup.
public void SetQuoteLineText (string sText) Sets the appropriate field for inserting Text type QuoteLine.
public void MoveLineAboveLine (QuoteLine lnAbove) Moves the QuoteLine position above the lnAbove position. The QuoteLine in lnAbove must point to an existing QuoteLine. This method essentially assigns the LineSortOrder property to the same value lnAbove holds and lnAbove is pushed down. You must call Save for the change to become effective.
public void MoveToBottom () Moves the QuoteLine position at the bottom of the Quote. This method essentially assigns the LineSortOrder property to -999 which is the value for the last position in the Quote. You must call Save for the change to become effective.
public void Delete () Deletes the QuoteLine.

Document Class

The CRM.Document class derives from CRM.Object and encapsulates the Document Fields. The following table lists all exposed CRM.Document properties.

Document Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string DocumentREC_ID FLDDOCRECID 20
public DateTime DocumentDate FLDDOCDOCDATE N/A
public string Subject FLDDOCDOCUMENTDESC 100
public string RelLinkREC_ID FLDDOCLINKRECID 20
public string AccountREC_ID FLDDOCCARDID 20
public string ContactREC_ID FLDDOCCONTACTID 20
public string Field1 FLDDOCTRANSPORT 20
public string Field2 FLDDOCFOLDER 20
public string Field3 FLDDOCUMENTPLACE 20
public string FilePathAndName FLDDOCDOCUMENTNAME 240
public int Category FLDDOCTREEID N/A
public string EmployeeREC_ID FLDDOCWORKERID 20
public string CreatedByUser FLDDOCCREATEUSER 20
public string LastUpdateByUser FLDDOCUPDATEUSER 20

HistoryNote Class

The CRM.HistoryNote class derives from CRM.Object and encapsulates the History Note Fields. The following table lists all exposed CRM.HistoryNote properties.

HistoryNote Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string HistoryNoteREC_ID FLDHISRECID 20
public DateTime Date FLDHISNOTEDATETIME N/A
public string Description FLDHISDESCRIPTION Unlimited
public string RelLinkREC_ID FLDHISLINKRECID 20
public string Field FLDHISUSER1 25
public string About FLDHISKIND 15
public string EmployeeREC_ID FLDHISWORKERID 20
public string AccountREC_ID FLDHISCARDID 20
public string Contact FLDHISCONTACTID 20
public string DocumentREC_ID FLDHISDOCID 20
public string CreatedByUser FLDHISCREATEUSER 20

Item Class

The CRM.Item class derives from CRM.Object and encapsulates the Item Fields. The following table lists all exposed CRM.Item properties.

Item Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string ItemREC_ID FLDITMRECID 20
public string ItemGroup FLDITMITEMTYPEGROUP 1
public string ItemCode FLDITMITEMNO 30
public string ItemName FLDITMNAME 60
public string PriceSource FLDITMPRICESOURCE 1
public string PricePerHour_Unit FLDITMUNITISHOUR 1
public double Price FLDITMUNITPRICE N/A
public double Cost FLDITMSTANDARDCOST N/A
public string Tax1 FLDITMTAXCODE1 3
public string Tax2 FLDITMTAXCODE2 3
public string Tax3 FLDITMTAXCODE3 3
public string DescriptionByName FLDITMDESCBYNAME 1
public string Description FLDITMDESC Unlimited
public string Suspend FLDITMSUSPENDED 1
public string Notes FLDITMNOTES Unlimited
public string Field1 FLDITMUSER1 25
public string CreateUser FLDITMCREATEUSER 20

KnowledgeBaseArticle Class

The CRM.KnowledgeBaseArticle class derives from CRM.Object and encapsulates the Knowledge Base Article Fields. The following table lists all exposed CRM.KnowledgeBaseArticle properties.

KnowledgeBaseArticle Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string KnowledgeBaseArticleREC_ID FLDKBARECID 20
public DateTime DocumentDate FLDKBACREATEDATE N/A
public string Title FLDKBATITLE 250
public string Problem FLDKBAPROBLEM Unlimited
public string Solution FLDKBASOLUTION Unlimited
public string Status FLDKBASTATUS 1
public string Category FLDKBACATEGORY 100
public string [Public] FLDKBAISPUBLIC 1
public string CreatedByUser FLDKBACREATEUSER 20
public string LastUpdateByUser FLDKBAUPDATEUSER 20

Opportunity Class

The CRM.Opportunity class derives from CRM.Object and encapsulates the Opportunity Fields. The following table lists all exposed CRM.Opportunity properties.

Opportunity Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string OpportunityREC_ID FLDOPPRECID 20
public string OpportunityName FLDOPPNAME 50
public string OpportunityID FLDOPPUSERID 15
public string AccountREC_ID FLDOPPCARDID 20
public string Source FLDOPPSOURCE 30
public DateTime CloseDate FLDOPPCLOSEDATE N/A
public string Manager FLDOPPWORKERID 20
public DateTime OpenDate FLDOPPOPENDATE N/A
public DateTime CloseByDate FLDOPPESTDATE N/A
public double Amount FLDOPPAMOUNT N/A
public double Probability FLDOPPPROBABILITY N/A
public string Stage FLDOPPSTAGE 30
public int Status FLDOPPSTATUS N/A
public double ClosingAmount FLDOPPCLOSEAMOUNT N/A
public string Description FLDOPPDESCRIPTION Unlimited
public string OpportunityType FLDOPPKIND 30
public string OpportunityReason FLDOPPREASON 30
public string Note FLDOPPNOTES Unlimited
public string Territory FLDOPPREGION 30
public string Field1 FLDOPPUSER1 30
public string Field2 FLDOPPUSER2 30
public string Field3 FLDOPPUSER3 30
public string CreatedByUser FLDOPPCREATEUSER 20
public string LastUpdateByUser FLDOPPUPDATEUSER 20

Contact Class

The CRM.Contact class derives from CRM.Object and it represents the secondary contacts to a CRM.Account. The following table lists all exposed CRM.Contact properties.

Contact Properties Reference Table

Access modifier Return value Property API Field Name Field length
public string ContactREC_ID FLDCRDRECID 20
public string ParentAccountREC_ID FLDCRDASSIGNCARDID 20
public int AccountType FLDCRDENTITYKIND N/A
public string CompanyName FLDCRDCOMPANY 60
public string Contact FLDCRDCONTACT 40
public string Salutation FLDCRDSUFFIX 20
public string Title FLDCRDTITLE
public string Department FLDCRDDEPARTMENT 35
public string Dear FLDCRDDEAR 20
public string LastName FLDCRDLASTNAME 20
public string AddressLine1 FLDCRDADDRESS1 40
public string AddressLine2 FLDCRDADDRESS2 40
public string AddressLine3 FLDCRDADDRESS3 40
public string City FLDCRDCITY 30
public string Country FLDCRDCOUNTRY 20
public string Zip FLDCRDZIP 15
public string State FLDCRDSTATE 30
public string EmailAddress1 FLDCRDEMAIL1 70
public string Phone1 FLDCRDPHONE1 25
public string Phone2 FLDCRDPHONE2 25
public string FaxNumber FLDCRDFAX1 25
public string Phone1Ext FLDCRDPHNDESC1 40
public string Phone2Ext FLDCRDPHNDESC2 40
public string FaxNumberExt FLDCRDFAXDESC1 15
public string SubContractCode FLDCRDSUBCODE 15
public DateTime Birthday FLDCRDBIRTHDAY N/A
public string Notes FLDCRDNOTES Unlimited
public DateTime CreationDate FLDCRDCREATEDATE N/A
public string CreatedByUser FLDCRDCREATEUSERID 20
public string LastUpdatedBy FLDCRDUPDATEUSERID 20

Config Class

CRM.Config class is used to pass the global configuration settings to the CRM.Application Initialize method.

Property Type Required Description
AppName string Yes Maximum 15 chars, string that best identifies your application.
DllFolder string Yes Exact path to the folder where RangerMSP API DLLs are located (CmtDbEng.dll and CmtDbQry.dll, usually "C:\\RangerMSP\\ThirdParty\\UserDev").
DbFolder string Yes Exact path to the folder where RangerMSP database is located (usually "C:\\RangerMSP\\db").
InitCRMApiDll bool No Initializes the CmtDbEng.dll file, which is required for proper functioning of all update functions. true by default (recommended setting). Set it to false only if you know what you are doing.
InitCRMQryDll bool No Initializes the CmtDbQry.dll file which is required for proper functioning of all search/query functions. true by default (recommended setting). Set it to false only if you know what you are doing.
Params List<string,string> No Not used, reserved for future use
RaiseExceptionIfDatabaseFieldTruncated bool No Specifies whether truncation of a field value will raise an exception. All string properties/fields have length limitations and if you overwrite them, the extra chars will be removed. By default this setting is false. Set it to true if you want truncation to raise an exception.

Application Class

The CRM.Application class implements a Singleton pattern that hold all global defined application settings and is used for easy access to these settings. Once the main CRM.Application object is initialized, you can refer to this instance by writing: CRM.Application.instance().

Table below lists the CRM.Application properties.

Property Type Description
config Config Access to the CRM.Config object passed in CRM.Application.Initialize method.
CmtDateFormat string Global RangerMSP date format (as dd/mm/yyyy or mm/dd/yyyy). You'll need to refer to this setting if you are directly manipulating DateTime field (using SetFieldValue method).
CmtDateSeparator string Separator between the date ranges, usually '/', '-' or '.'.
CmtTimeFormat string Global RangerMSP time format.
CmtIsTimeFormatAMPMInUse bool 12 hour or 24 hour time format.

Table below list the CRM.Application methods.

Access modifier Return value Method Arguments Description
public static Application instance () Method that returns the singleton object. Use it to access all CRM.Application properties/methods.
public static void Initialize (Config c) Method that initializes the internal RangerMSP API DLLs. Must be the first call before using any other RangerMSP library calls.
public static void Terminate () Terminates all RangerMSP internal resources. You should call this method before exit from your application.

CrmField Class

The CRM.CrmField class holds the basic attributes for each database field. For each of the classes that represent RangerMSP objects (Account, Ticket, etc.) there is a preinitialized set of shared CRM.CrmField objects that correspond to the properties defined for the class. For example, the CRM.Account class has a property FileAs (CRM.Account.FileAs). To this property corresponds one shared object instance of the CRM.CrmField class accessible through CRM.Account.Fields.FileAs. To the property LastName (CRM.Account.LastName), corresponds the shared object CRM.Account.Fields.LastName of type CRM.CrmField. And so on, for each property in each class.

Below is a table that lists the properties available in the CRM.CrmField class.

Property Type Description
Key string The internal database field key (as FLDCRDFULLNAME or FLDCRDLASTNAME, etc.)
Type string Internal database field type (as CHAR, MEMO, DOUBLE, TIMESTAMP, etc.)
Size int Maximum allowed length for the field data (applies to CHAR Type).
Label string Label for the field
Hint string
Name string
DefaultValue string Default value for the field
DisplaySymbol string For fields that represent currency value this can be $ (for dollar), or for percentage values this can be %

We demonstrate the above in the following sample: 

//charge is of type CRM.Charge and is previously initialized
Console.Out.Write(charge.AdjustAmount.ToString() + CRM.Charge.Fields.AdjustAmount.DisplaySymbol);

ObjectQuery Class

CRM.ObjectQuery is a generics class that can operate with any of the CRM.Object derived classes. It is used to query for objects of certain type (Account, Ticket, etc.). For example, the following code snippet searches for all tickets of an account updated since certain date: 

CRM.ObjectQuery<CRM.Ticket> ticketSearch = new CRM.ObjectQuery<CRM.Ticket>();
//account is previously initialized
ticketSearch.AddCriteria(CRM.Ticket.Fields.AccountREC_ID, CRM.OperatorEnum.opEqual, account.AccountREC_ID);
ticketSearch.AddCriteria(CRM.Ticket.Fields.UpdateDate, CRM.OperatorEnum.opGreaterThanOrEqual, DateTime.Parse("01 Jan 2011"));
List<CRM.Ticket> tickets = ticketSearch.FetchObjects();
//tickets now contains all CRM.Ticket objects that satisfy the above criteria.

By default, CRM.ObjectQuery.AddCriteria method uses the logical AND operator to link the conditions. Thus, in case more than one condition are added, all have to be satisfied in order for an object to get into the search results.

In case we want to search for objects and it is enough to satisfy any of the criteria, we can use the OR operator, as in the example below: 

CRM.ObjectQuery<CRM.Account> accountSearch = new CRM.ObjectQuery<CRM.Account>(CRM.LinkEnum.linkOR);
accountSearch.AddCriteria(CRM.Account.Fields.City, CRM.OperatorEnum.opEqual, "New York");
accountSearch.AddCriteria(CRM.Account.Fields.City, CRM.OperatorEnum.opEqual, "Chicago");
List<CRM.Account> accounts = accountSearch.FetchObjects();
//accounts now contains all CRM.Account objects that satisfy the above criteria.

If our search returns lots of objects, it may take some time to get the results back. If not all of the object's fields are need for the given task, we can pass a comma separated string with the field names to the CRM.ObjectQuery.FetchObjects and the objects in the results will have only those fields populated. 

CRM.ObjectQuery<CRM.Account> accountSearch = new CRM.ObjectQuery<CRM.Account>(CRM.LinkEnum.linkOR);
accountSearch.AddCriteria(CRM.Account.Fields.City, CRM.OperatorEnum.opEqual, "New York");
accountSearch.AddCriteria(CRM.Account.Fields.City, CRM.OperatorEnum.opEqual, "Chicago");
List<CRM.Account> accounts = accountSearch.FetchObjects(CRM.Account.Fields.AccountREC_ID.Key + "," + CRM.Account.Fields.City.Key);
//accounts now contains all CRM.Account objects that satisfy the above criteria.

The table below explains the important methods of the CRM.ObjectQuery class:

Access modifier Return value Method Arguments Description
public void AddCriteria (string sField, OperatorEnum opEnum, string sValue) Adds one criteria to the initialized CRM.ObjectQuery object instance.

First parameter is the internal field name (column API Field name in the Object derived classes tables), second parameter is the criteria operator (see the table below) and third parameter is the value to search for. This variation of the AddCriteria method should be used only when searching in a field whose name is not included in the predefined fields.

public void AddCriteria (CrmField field, OperatorEnum opEnum, string sValue) Adds one criteria to the initialized CRM.ObjectQuery object instance.

First parameter is one of the CRM.CrmField preinitialized objects included in Fields class in each of the CRM.Object derived classes, second parameter is the criteria operator (see the table below) and third parameter is the value (System.String) to search for. This variation (or the one variations with the System.DateTime or System.Double as third parameter) of the AddCriteria method is the preferred way of adding criteria, unless there is no preinitialized CRM.CrmField object for the field.

public void AddCriteria (CrmField field, OperatorEnum opEnum, DateTime dtValue) Adds one criteria to the initialized CRM.ObjectQuery object instance.

First parameter is one of the CRM.CrmField preinitialized objects included in Fields class in each of the CRM.Object derived classes, second parameter is the criteria operator (see the table below) and third parameter is the value (System.DateTime) to search for. Use this variation to search in fields that are of DateTime type.

public void AddCriteria (CrmField field, OperatorEnum opEnum, int nValue) Adds one criteria to the initialized CRM.ObjectQuery object instance.

First parameter is one of the CRM.CrmField preinitialized objects included in Fields class in each of the CRM.Object derived classes, second parameter is the criteria operator (see the table below) and third parameter is the value (System.Integer) to search for. Use this variation to search in fields that are of Integer type.

public void AddCriteria (CrmField field, OperatorEnum opEnum, double nValue) Adds one criteria to the initialized CRM.ObjectQuery object instance.

First parameter is one of the CRM.CrmField preinitialized objects included in Fields class in each of the CRM.Object derived classes, second parameter is the criteria operator (see the table below) and third parameter is the value (System.Double) to search for. Use this variation to search in fields that are of Double type.

public void AddSortExpression (string sField, SortDirectionEnum sortEnum) Adds a sort expression to the initialized CRM.ObjectQuery object instance.

First parameter is the internal field name (column API Field name in the Object derived classes tables), second parameter is CRM.SortDirectionEnum (sortASC or sortDESC).

public void AddSortExpression (CrmField field, SortDirectionEnum sortEnum) Adds a sort expression to the initialized CRM.ObjectQuery object instance.

First parameter is one of the CRM.CrmField preinitialized objects included in Fields class in each of the CRM.Object derived classes, second parameter is CRM.SortDirectionEnum (sortASC or sortDESC).

public List<T> FetchObjects () Executes the constructed query and returns a list of objects (of type T where T is any of the CRM.Object derived classes) that satisfies the criteria.

Below is the table with the available operators (CRM.OperatorEnum) used in the AddCriteria methods.

Enum value Description
CRM.OperatorEnum.opEqual Searches for objects using the exact match (equals) operator
CRM.OperatorEnum.opGreaterThan Searches for objects whose value is greater than the value passed in the third parameter in AddCriteria method.
CRM.OperatorEnum.opGreaterThanOrEqual Searches for objects whose value is greater or equal than the value passed in the third parameter in AddCriteria method.
CRM.OperatorEnum.opLessThan Searches for objects whose value is less than the value passed in the third parameter in AddCriteria method.
CRM.OperatorEnum.opLessThanOrEqual Searches for objects whose value is less than or equal the value passed in the third parameter in AddCriteria method.
CRM.OperatorEnum.opLike Combined with % (percent sign) in the value passed in the third parameter in AddCriteria method can be used for search with broader match.
CRM.OperatorEnum.opNot Searches for objects whose value differs from the one passed in the third parameter in AddCriteria method.
CRM.OperatorEnum.opNotLike

Field length limitations

Most of the database fields (analogous the properties mapped to these fields) have limits on data length that can be accepted. If more than the allowed length is assigned to a field, data is truncated to the length the field is capable of holding and the rest is discarded. Depending on the CRM.Config.RaiseExceptionIfDatabaseFieldTruncated setting (true/false), the operation could raise an exception alerting you that not all of the data was accepted. By default this setting is off (false) resulting in silent truncation of the extra data. Set the CRM.Config.RaiseExceptionIfDatabaseFieldTruncated to true if this behavior is not acceptable.

Below is an example of how to switch this setting ON: 

CRM.Config config = new CRM.Config();
config.AppName = "C# Demo";
config.DllFolder = "C:\\RangerMSP\\ThirdParty\\UserDev";
config.DbFolder = "C:\\RangerMSP\\db";
config.RaiseExceptionIfDatabaseFieldTruncated = true;//the setting is ON now

//Initialize the CRM.Application
CRM.Application.Initialize(config);

CRM.Account account = new CRM.Account();
account.FileAs = "ACME Company";
account.Dear = "Mr.";
account.Contact = "John Doe";
//the following line of code will throw an exception because we try to assign more than 40 chars to AddressLine1
account.AddressLine1 = "More than forty characters of the main address line";//Exception is thrown here
account.Save();

See Also

Retrieved from "http://www.rangermsp.com/w/index.php?title=CSharp_API&oldid=8582"