CSharp API

Disclaimer

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

Introduction

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

System Requirements

• CommitCRM 5.6 or later.
• Visual C# .NET 2008 or Visual C# .NET 2010.
• CommitLib.dll (the CommitCRM 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 CommitLib.dll file, in order to have access to the CommitCRM library classes.

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

Local Server

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

• AppName

This is free text, preferably the name of your application.

• CommitDllFolder

Behind the scenes the library uses the two CommitCRM API dlls: CmtDbEng.dll and CmtDbQry.dll.

In the default CommitCRM installation you'll find these files in 'C:\\Commit\\ThirdParty\\UserDev'.

Important Note: Always point to this folder and do not copy the dll files elsewhere. This is because when the CommitCRM version upgrade runs it also upgrades the dll files stored in this folder. This verifies that you will always be using the latest release.

• CommitDbFolder

Path to the CommitCRM database, default is 'C:\\Commit\\db'.

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

CommitCRM.Config config = new CommitCRM.Config();
config.AppName = "C# Demo";
config.CommitDllFolder = "C:\\Commit\\ThirdParty\\UserDev";
config.CommitDbFolder = "C:\\Commit\\db";

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

Web API

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

• AppName

This is free text, preferably the name of your application.

• WebAPIUrl

Url to the CommitCRM server running the Web API, either local or remote. Valid examples include http://localhost:4964/ and https://webapi.mycommitcrmserver.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 CommitCRM.Config object like this:

CommitCRM.Config config = new CommitCRM.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 CommitCRM server or remote CommitCRM server running the Web API.

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

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

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

Before exit, we terminate the CommitCRM.Application object:

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

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

try
{
    CommitCRM.Config config = new CommitCRM.Config();
    config.AppName = "C# Demo";
    config.CommitDllFolder = "C:\\Commit\\ThirdParty\\UserDev";
    config.CommitDbFolder = "C:\\Commit\\db";

    CommitCRM.Application.Initialize(config);

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

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

The library exposes as C# classes the same CommitCRM objects (Account, Ticket etc.) available through the native CommitCRM 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 CommitCRM.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 CommitCRM.Account objects. We instantiate an object of the CommitCRM.ObjectQuery class and pass CommitCRM.Account class as generics parameter.

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

CommitCRM.ObjectQuery class can accept any of the CommitCRM 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(CommitCRM.Account.Fields.City, CommitCRM.OperatorEnum.opEqual, "New York");

Тhe first parameter to the AddCriteria method is either a static object instance of CommitCRM.CmtField 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 CommitCRM.Account class.

The second parameter is a compare operator. We here use the CommitCRM.OperatorEnum.opEqual to get only exact matches. In order to get a broader match in the results you can use CommitCRM.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 CommitCRM.OperatorEnum.opLike operator, will match the phrase even if in the middle of a sentence.

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

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

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

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

Or we can manipulate these accounts:

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

We invoke the CommitCRM.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 CommitCRM database. For an existing account, invoking the Save method would update the fields we modified in the existing account. This rule applies to all CommitCRM objects.

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

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

GetFieldValue and SetFieldValue methods

Each of the CommitCRM 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 CommitCRM 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 (CommitCRM.Account account in accounts)
{
    CommitCRM.Ticket ticket = new CommitCRM.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 CommitCRM C# library, some operations can fail. In this case the library will throw an exception of the CommitCRM.Exception class. We recommend enclosing all calls to the CommitCRM 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 CommitCRM.Exception.Status property that holds the last CommitCRM Status value, or inspect the list of CommitCRM.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 CommitCRM_CSharp
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                CommitCRM.Config config = new CommitCRM.Config();
                config.AppName = "C# Demo";
                config.CommitDllFolder = "C:\\Commit\\ThirdParty\\UserDev";
                config.CommitDbFolder = "C:\\Commit\\db";

                CommitCRM.Application.Initialize(config);

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

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

                foreach (CommitCRM.Account account in accounts)
                {
                    Console.Out.WriteLine(account.CompanyName);
                }
            }
            catch (CommitCRM.Exception exc)
            {
               //here we catch commit specific error
               //we can inspect the Commit 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
            {
                CommitCRM.Application.Terminate();
            }
        }
    }
}

Classes and Objects

The CommitCRM 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 CommitCRM.Object class).
2. Class data fields, providing an easy way to update the object's data.

All CommitCRM'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 CommitCRM.Application was initialized successfully), one would use the following code snippet:

CommitCRM.Account account = new CommitCRM.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 CommitCRM.Object class is the base class for all CommitCRM accessible objects (as Ticket, Account, Asset, etc.). The public methods exposed by the CommitCRM.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 CommitCRM.Object class and map directly to a native Commit CRM object (Account, Ticket, etc.).

Account Class

The CommitCRM.Account class derives from CommitCRM.Object and encapsulates the Account Fields. The following table lists all exposed CommitCRM.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 CommitCRM.Ticket class derives from CommitCRM.Object and encapsulates the Ticket Fields. The following table lists all exposed CommitCRM.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 CommitCRM.Asset class derives from CommitCRM.Object and encapsulates the Asset Fields. The following table lists all exposed CommitCRM.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 CommitCRM.Calendar class derives from CommitCRM.Object and encapsulates the Calendar Fields. The following table lists all exposed CommitCRM.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

Charge Class

The CommitCRM.Charge class derives from CommitCRM.Object and encapsulates the Charge Fields. The following table lists all exposed CommitCRM.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	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 CommitCRM.Quote class derives from CommitCRM.Object. The following table lists all exposed CommitCRM.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 CommitCRM.QuoteLine class derives from CommitCRM.Object. The following table lists all exposed CommitCRM.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 CommitCRM.Document class derives from CommitCRM.Object and encapsulates the Document Fields. The following table lists all exposed CommitCRM.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 CommitCRM.HistoryNote class derives from CommitCRM.Object and encapsulates the History Note Fields. The following table lists all exposed CommitCRM.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 CommitCRM.Item class derives from CommitCRM.Object and encapsulates the Item Fields. The following table lists all exposed CommitCRM.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 CommitCRM.KnowledgeBaseArticle class derives from CommitCRM.Object and encapsulates the Knowledge Base Article Fields. The following table lists all exposed CommitCRM.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 CommitCRM.Opportunity class derives from CommitCRM.Object and encapsulates the Opportunity Fields. The following table lists all exposed CommitCRM.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 CommitCRM.Contact class derives from CommitCRM.Object and it represents the secondary contacts to a CommitCRM.Account. The following table lists all exposed CommitCRM.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

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

Property	Type	Required	Description
AppName	string	Yes	Maximum 15 chars, string that best identifies your application.
CommitDllFolder	string	Yes	Exact path to the folder where CommitCRM API DLLs are located (CmtDbEng.dll and CmtDbQry.dll, usually "C:\\Commit\\ThirdParty\\UserDev").
CommitDbFolder	string	Yes	Exact path to the folder where CommitCRM database is located (usually "C:\\Commit\\db").
InitCommitApiDll	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.
InitCommitQryDll	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 CommitCRM.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 CommitCRM.Application object is initialized, you can refer to this instance by writing: CommitCRM.Application.instance().

Table below lists the CommitCRM.Application properties.

Property	Type	Description
config	Config	Access to the CommitCRM.Config object passed in CommitCRM.Application.Initialize method.
CmtDateFormat	string	Global CommitCRM 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 CommitCRM time format.
CmtIsTimeFormatAMPMInUse	bool	12 hour or 24 hour time format.

Table below list the CommitCRM.Application methods.

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

CmtField Class

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

Below is a table that lists the properties available in the CommitCRM.CmtField 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 CommitCRM.Charge and is previously initialized
Console.Out.Write(charge.AdjustAmount.ToString() + CommitCRM.Charge.Fields.AdjustAmount.DisplaySymbol);

ObjectQuery Class

CommitCRM.ObjectQuery is a generics class that can operate with any of the CommitCRM.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:

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

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

Access modifier	Return value	Method	Arguments	Description
public	void	AddCriteria	(string sField, OperatorEnum opEnum, string sValue)	Adds one criteria to the initialized CommitCRM.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	(CmtField field, OperatorEnum opEnum, string sValue)	Adds one criteria to the initialized CommitCRM.ObjectQuery object instance. First parameter is one of the CommitCRM.CmtField preinitialized objects included in Fields class in each of the CommitCRM.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 CommitCRM.CmtField object for the field.
public	void	AddCriteria	(CmtField field, OperatorEnum opEnum, DateTime dtValue)	Adds one criteria to the initialized CommitCRM.ObjectQuery object instance. First parameter is one of the CommitCRM.CmtField preinitialized objects included in Fields class in each of the CommitCRM.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	(CmtField field, OperatorEnum opEnum, int nValue)	Adds one criteria to the initialized CommitCRM.ObjectQuery object instance. First parameter is one of the CommitCRM.CmtField preinitialized objects included in Fields class in each of the CommitCRM.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	(CmtField field, OperatorEnum opEnum, double nValue)	Adds one criteria to the initialized CommitCRM.ObjectQuery object instance. First parameter is one of the CommitCRM.CmtField preinitialized objects included in Fields class in each of the CommitCRM.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 CommitCRM.ObjectQuery object instance. First parameter is the internal field name (column API Field name in the Object derived classes tables), second parameter is CommitCRM.SortDirectionEnum (sortASC or sortDESC).
public	void	AddSortExpression	(CmtField field, SortDirectionEnum sortEnum)	Adds a sort expression to the initialized CommitCRM.ObjectQuery object instance. First parameter is one of the CommitCRM.CmtField preinitialized objects included in Fields class in each of the CommitCRM.Object derived classes, second parameter is CommitCRM.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 CommitCRM.Object derived classes) that satisfies the criteria.

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

Enum value	Description
CommitCRM.OperatorEnum.opEqual	Searches for objects using the exact match (equals) operator
CommitCRM.OperatorEnum.opGreaterThan	Searches for objects whose value is greater than the value passed in the third parameter in AddCriteria method.
CommitCRM.OperatorEnum.opGreaterThanOrEqual	Searches for objects whose value is greater or equal than the value passed in the third parameter in AddCriteria method.
CommitCRM.OperatorEnum.opLessThan	Searches for objects whose value is less than the value passed in the third parameter in AddCriteria method.
CommitCRM.OperatorEnum.opLessThanOrEqual	Searches for objects whose value is less than or equal the value passed in the third parameter in AddCriteria method.
CommitCRM.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.
CommitCRM.OperatorEnum.opNot	Searches for objects whose value differs from the one passed in the third parameter in AddCriteria method.
CommitCRM.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 CommitCRM.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 CommitCRM.Config.RaiseExceptionIfDatabaseFieldTruncated to true if this behavior is not acceptable.

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

CommitCRM.Config config = new CommitCRM.Config();
config.AppName = "C# Demo";
config.CommitDllFolder = "C:\\Commit\\ThirdParty\\UserDev";
config.CommitDbFolder = "C:\\Commit\\db";
config.RaiseExceptionIfDatabaseFieldTruncated = true;//the setting is ON now

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

CommitCRM.Account account = new CommitCRM.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

• Commit API Developers Guide
• API Reference Manual