VB.NET API

User Manuals > API Developers Guide > VB.NET 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 VB.NET 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 Basic .NET 2008 or Visual Basic .NET 2010.
• CommitLib.dll (the CommitCRM VB.NET compiled library).

Getting Started

After you create your VB.NET 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 configured with 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:

Dim config As New CommitCRM.Config
config.AppName = "VB.NET Demo"
config.CommitDllFolder = "C:\Commit\ThirdParty\UserDev"
config.CommitDbFolder = "C:\Commit\db"

You should of course check where these paths are exactly on your disk and modify these values accordingly.

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

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:

CommitCRM.Application.Terminate()

The most basic VB.NET application that just connects to CommitCRM and terminates could look something like this:

Try
    Dim config As New CommitCRM.Config
    config.AppName = "VB.NET 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 ex As Exception 
    Console.Out.Write(ex.Message)
Finally
    CommitCRM.Application.Terminate()
End Try

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 VB.NET 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.

Dim accountSearch As New CommitCRM.ObjectQuery(Of 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("FLDCRDCITY", CommitCRM.OperatorEnum.opEqual, "New York")

The first parameter to the AddCriteria method is either a Shared object instance of CommitCRM.CmtField class representing the field we want to look in or the internal API field name. Refer to column API Field Name 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):

Dim accounts As List(Of CommitCRM.Account) = 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 For Each - Next statement to iterate through the accounts:

For Each account In accounts
    Console.Out.Write(account.CompanyName + vbCrLf)
Next

Or we can manipulate these accounts:

For Each account In accounts
    If account.Zip.Length = 0 Then
        account.Zip = "10001"
        account.Save()
    End If
Next

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 options is to add a new ticket for each of the accounts:

For Each account In accounts
    Dim ticket As New CommitCRM.Ticket
    ticket.AccountREC_ID = account.AccountREC_ID
    ticket.Description = "Sample ticket for a NewYork account"
    ticket.Save()
Next

GetFieldValue and SetFieldValue methods

Each of the CommitCRM library objects have a set of properties that are exposed as VB.NET 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:

For Each account In accounts
    Dim ticket As New CommitCRM.Ticket
    ticket.SetFieldValue("FLDTKTCARDID", account.GetFieldValue("FLDCRDRECID"))
    ticket.SetFieldValue("FLDTKTPROBLEM", "Sample ticket for a NewYork account")
    ticket.Save()
Next

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

Exception Handling

While working with the CommitCRM VB.NET 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

Module Module1

    Sub Main()

        Try
            'Setup the CommitCRM.Config object
            Dim config As New CommitCRM.Config
            config.AppName = "VB.NET Demo"
            config.CommitDllFolder = "C:\Commit\ThirdParty\UserDev"
            config.CommitDbFolder = "C:\Commit\db"

            'Initialize the CommitCRM.Application
            CommitCRM.Application.Initialize(config)

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

            'search for "New York" in the FLDCRDCITY field
            Dim accountSearch As New CommitCRM.ObjectQuery(Of CommitCRM.Account)
            accountSearch.AddCriteria("FLDCRDCITY", CommitCRM.OperatorEnum.opEqual, "New York")
            Dim accounts As List(Of CommitCRM.Account) = accountSearch.FetchObjects()

            'loop through the retrieved accounts and output the CompanyName
            For Each account In accounts
                Console.Out.Write(account.CompanyName + vbCrLf)
            Next

       Catch ex As CommitCRM.Exception '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(ex.Message)

        Catch ex As Exception 
            Console.Out.Write(ex.Message)
        Finally
            CommitCRM.Application.Terminate()
        End Try
    End Sub

End Module

Classes and Objects

The CommitCRM VB.NET 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:

Dim account As 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 routines and functions exposed by the CommitCRM.Object class are available to the derived classes.

Object Method Reference Table

Access modifier	Method	Arguments	Return value	Description
Public Sub	SetFieldValue	(sKey As String, sValue As String)		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 Function	GetFieldValue	(sKey As String)	As String	Retrieves the value of the field passed in sKey argument. Use this method to access user-defined custom fields.
Public Sub	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 Sub	Reinit	(sID As String)		Same as Reload except the unique identifier is passed as argument.
Public Sub	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	Property	API Field Name	Return value	Field length
Public ReadOnly Property	AccountREC_ID	FLDCRDRECID	As String	20
Public Property	AccountManager	FLDCRDASSIGNCARDID	As String	20
Public Property	CompanyName	FLDCRDCOMPANY	As String	60
Public Property	Contact	FLDCRDCONTACT	As String	40
Public Property	Assistant	FLDCRDASSISTANT	As String	20
Public Property	ContractREC_ID	FLDCRDBCRECID	As String	20
Public Property	AccountNumber	FLDCRDCARDID2	As String	15
Public Property	ID	FLDCRDCARDID3	As String	15
Public Property	PopupMessage	FLDCRDCARDMESSAGE	As String	Unlimited
Public Property	AddressLine1	FLDCRDADDRESS1	As String	40
Public Property	AddressLine2	FLDCRDADDRESS2	As String	40
Public Property	AddressLine3	FLDCRDADDRESS3	As String	40
Public Property	City	FLDCRDCITY	As String	30
Public Property	Country	FLDCRDSTATE	As String	20
Public Property	State	FLDCRDCOUNTRY	As String	30
Public Property	Zip	FLDCRDZIP	As String	15
Public Property	CreationDate	FLDCRDCREATEDATE	As DateTime	N/A
Public Property	CreatedByUser	FLDCRDCREATEUSERID	As String	20
Public Property	Dear	FLDCRDDEAR	As String	20
Public Property	Department	FLDCRDDEPARTMENT	As String	35
Public Property	DocumentsStoreDirectory	FLDCRDDOCSFOLDER	As String	100
Public Property	EmailAddress1	FLDCRDEMAIL1	As String	70
Public Property	EmailAddress2	FLDCRDEMAIL2	As String	70
Public Property	AccountType	FLDCRDENTITYKIND	As Integer	N/A
Public Property	FaxNumber	FLDCRDFAX1	As String	25
Public Property	FaxNumberExt	FLDCRDFAXDESC1	As String	15
Public Property	FileAs	FLDCRDFULLNAME	As String	60
Public Property	Type	FLDCRDKIND	As String	30
Public Property	LastName	FLDCRDLASTNAME	As String	20
Public Property	Notes	FLDCRDNOTES	As String	Unlimited
Public Property	Field	FLDCRDPERSONID	As String	20
Public Property	Phone1Ext	FLDCRDPHNDESC1	As String	40
Public Property	Phone2Ext	FLDCRDPHNDESC2	As String	40
Public Property	Phone3Ext	FLDCRDPHNDESC3	As String	15
Public Property	Phone4Ext	FLDCRDPHNDESC4	As String	15
Public Property	Phone1	FLDCRDPHONE1	As String	25
Public Property	Phone2	FLDCRDPHONE2	As String	25
Public Property	Phone3	FLDCRDPHONE3	As String	25
Public Property	Phone4	FLDCRDPHONE4	As String	25
Public Property	Region	FLDCRDREGIONCODE	As String	15
Public Property	PopupMessageDisplayIndication	FLDCRDSHOWMESSAGE	As String	1
Public Property	SubContractCode	FLDCRDSUBCODE	As String	15
Public Property	Salutation	FLDCRDSUFFIX	As String	20
Public Property	Tax1	FLDCRDTAXCODE1	As String	3
Public Property	Tax2	FLDCRDTAXCODE2	As String	3
Public Property	Title	FLDCRDTITLE	As String	30
Public Property	LastUpdatedBy	FLDCRDUPDATEUSERID	As String	20
Public Property	WebAddress1	FLDCRDURL1	As String	100
Public Property	WebAddress2	FLDCRDURL2	As String	100
Public Property	Status	FLDCRDUSER1	As String	30
Public Property	Field1	FLDCRDUSER2	As String	30
Public Property	Field2	FLDCRDUSER3	As String	30
Public Property	Field3	FLDCRDUSER4	As String	30
Public Property	Field4	FLDCRDUSER5	As String	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	Property	API Field Name	Return value	Field length
Public ReadOnly Property	TicketREC_ID	FLDTKTRECID	As String	20
Public Property	AccountREC_ID	FLDTKTCARDID	As String	20
Public Property	AssetREC_ID	FLDTKTASSETRECID	As String	20
Public Property	ContactREC_ID	FLDTKTCONTACTID	As String	20
Public Property	ContractREC_ID	FLDTKTBCRECID	As String	20
Public Property	EmployeeREC_ID	FLDTKTWORKERID	As String	20
Public Property	TicketPriority	FLDTKTPRIORITY	As Integer	N/A
Public Property	TicketNumber	FLDTKTTICKETNO	As String	20
Public Property	Description	FLDTKTPROBLEM	As String	Unlimited
Public Property	TicketType	FLDTKTKIND	As String	25
Public Property	Source	FLDTKTSOURCE	As String	30
Public Property	EstimatedDurationTime	FLDTKTSCHEDLENESTIM	As Integer	N/A
Public Property	ShowTicketInDispatcher	FLDTKTFORDISPATCH	As String	1
Public Property	Status	FLDTKTSTATUS	As Integer	N/A
Public Property	CreatedByUser	FLDTKTCREATEUSER	As String	20
Public Property	DueDate	FLDTKTDUEDATETIME	As DateTime	N/A
Public Property	Resolution	FLDTKTSOLUTION	As String	Unlimited
Public ReadOnly Property	UpdateDate	FLDTKTUPDATEDATE	As DateTime	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	Property	API Field Name	Return value	Field length
Public ReadOnly Property	AssetREC_ID	FLDASTRECID	As String	20
Public Property	AssetCode	FLDASTASSETCODE	As String	30
Public Property	AssetType	FLDASTASSETTYPE	As String	1
Public Property	AssetName	FLDASTNAME	As String	60
Public Property	Status	FLDASTSTATUS	As String	1
Public Property	SerialNo	FLDASTSERIALNO	As String	30
Public Property	AccountREC_ID	FLDASTACCRECID	As String	20
Public Property	ContactREC_ID	FLDASTCONTACTRECID	As String	20
Public Property	CreatedByUser	FLDASTCREATEUSER	As String	20
Public Property	PurchaseDate	FLDASTCUSTPURDATE	As DateTime	N/A
Public Property	PurchasedFromUs	FLDASTCUSTPURFROMUS	As String	1
Public Property	PurchaseInvoice	FLDASTCUSTPUROURINV	As String	15
Public Property	CustomerPO	FLDASTCUSTPURPO	As String	15
Public Property	PurchasePrice	FLDASTCUSTPURPRICE	As Double	N/A
Public Property	DeliveredDate	FLDASTDELIVEDATE	As DateTime	N/A
Public Property	Description	FLDASTDESC	As String	Unlimited
Public Property	InstalledBy	FLDASTINSTALBY	As String	20
Public Property	InstalledDate	FLDASTINSTALDATE	As DateTime	N/A
Public Property	LicenseCodes	FLDASTLICENSECODE	As String	Unlimited
Public Property	LicenseKeys	FLDASTLICENSEKEYS	As String	Unlimited
Public Property	LicenseNotes	FLDASTLICENSENOTES	As String	Unlimited
Public Property	Location	FLDASTLOCATION	As String	50
Public Property	Manufacturer	FLDASTMANUFACTURER	As String	40
Public Property	MnfSerialNo	FLDASTMNFSERIALNO	As String	30
Public Property	Model	FLDASTMODEL	As String	20
Public Property	Notes	FLDASTNOTES	As String	Unlimited
Public Property	Quantity	FLDASTQUANTITY	As Double	N/A
Public Property	LastUpdateBy	FLDASTUPDATEUSER	As String	20
Public Property	Field1	FLDASTUSER1	As String	25
Public Property	Field2	FLDASTUSER2	As String	25
Public Property	Field3	FLDASTUSER3	As String	25
Public Property	Field4	FLDASTUSER4	As String	25
Public Property	Field5	FLDASTUSER5	As String	25
Public Property	Date1	FLDASTUSERDATE1	As DateTime	N/A
Public Property	Number1	FLDASTUSERNUMBER1	As Double	N/A
Public Property	VendorPurchasedDate	FLDASTVENDORDATEPURC	As DateTime	N/A
Public Property	VendorInvoice	FLDASTVENDORINVNO	As String	15
Public Property	VendorPO	FLDASTVENDOROURPO	As String	15
Public Property	VendorPrice	FLDASTVENDORPRICE	As Double	N/A
Public Property	Vendor	FLDASTVENDORRECID	As String	20
Public Property	VendorSerialNo	FLDASTVENDORSERNO	As String	30
Public Property	VendorWarrantyExpDate	FLDASTVENDORWARREXP	As DateTime	N/A
Public Property	Version	FLDASTVERSION	As String	15
Public Property	WarrantyLicenseExp	FLDASTWARREXPDATE	As DateTime	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	Property	API Field Name	Return value	Field length
Public ReadOnly Property	CalendarREC_ID	FLDEVTRECID	As String	20
Public Property	EventType	FLDEVTWRITETOID	As Integer	N/A
Public Property	EmployeeREC_ID	FLDEVTWORKERID	As String	20
Public Property	PrivateUser	FLDEVTPRIVATEID	As String	20
Public Property	AccountREC_ID	FLDEVTCARDID	As String	20
Public Property	ContactREC_ID	FLDEVTCONTACTID	As String	20
Public Property	DocumentREC_ID	FLDEVTDOCID	As String	20
Public Property	DoneIndication	FLDEVTDONE	As Boolean	N/A
Public Property	[Date]	FLDEVTEVENTDATE	As DateTime	N/A
Public Property	Description	FLDEVTFREETEXT	As String	Unlimited
Public Property	TimeStart	FLDEVTFROMTIME	As String	N/A
Public Property	TimeEnd	FLDEVTTOTIME	As String	N/A
Public Property	RelLinkREC_ID	FLDEVTLINKRECID	As String	20
Public Property	Field1	FLDEVTFAMILY	As String	50
Public Property	Field2	FLDEVTACTION	As String	50
Public Property	Field3	FLDEVTPLACE	As String	40
Public Property	Field4	FLDEVTPLACE1	As String	30
Public Property	Field5	FLDEVTPLACE2	As String	30
Public Property	CreatedByUser	FLDEVTCREATEUSERID	As String	20
Public Property	LastUpdateByUser	FLDEVTUPDATEUSER	As String	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	Property	API Field Name	Return value	Field length
Public ReadOnly Property	ChargeREC_ID	FLDSLPRECID	As String	20
Public Property	ChargeSource	FLDSLPSOURCERECID	As String	20
Public Property	AccountREC_ID	FLDSLPCARDID	As String	20
Public Property	EmployeeREC_ID	FLDSLPWORKERID	As String	20
Public Property	ChargedItem	FLDSLPITEMID	As String	20
Public Property	ContractREC_ID	FLDSLPBCRECID	As String	20
Public Property	TicketREC_ID	FLDSLPTICKETID	As String	20
Public Property	[Date]	FLDSLPSLIPDATE	As DateTime	N/A
Public Property	Description	FLDSLPDESC	As String	Unlimited
Public Property	Units_Hours	FLDSLPQUANTITY	As Double	N/A
Public Property	AdjustAmount	FLDSLPADJUSTAMOUNT	As Double	N/A
Public Property	AdjustPercent	FLDSLPADJUSTPERCENT	As Double	N/A
Public Property	FromTime	FLDSLPSTARTTIME	As String	N/A
Public Property	ToTime	FLDSLPENDTIME	As String	N/A
Public Property	Price_Rate	FLDSLPPRICE	As Double	N/A
Public Property	Billable	FLDSLPBILLKIND	As String	1
Public Property	Billed	FLDSLPSTAGE	As String	1
Public Property	Field1	FLDSLPUSER1	As String	25
Public Property	CreateUser	FLDSLPCREATEUSER	As String	20

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	Property	API Field Name	Return value	Field length
Public ReadOnly Property	DocumentREC_ID	FLDDOCRECID	As String	20
Public Property	DocumentDate	FLDDOCDOCDATE	As DateTime	N/A
Public Property	Subject	FLDDOCDOCUMENTDESC	As String	100
Public Property	RelLinkREC_ID	FLDDOCLINKRECID	As String	20
Public Property	AccountREC_ID	FLDDOCCARDID	As String	20
Public Property	ContactREC_ID	FLDDOCCONTACTID	As String	20
Public Property	Field1	FLDDOCTRANSPORT	As String	20
Public Property	Field2	FLDDOCFOLDER	As String	20
Public Property	Field3	FLDDOCUMENTPLACE	As String	20
Public Property	FilePathAndName	FLDDOCDOCUMENTNAME	As String	240
Public Property	Category	FLDDOCTREEID	As Integer	N/A
Public Property	EmployeeREC_ID	FLDDOCWORKERID	As String	20
Public Property	CreatedByUser	FLDDOCCREATEUSER	As String	20
Public Property	LastUpdateByUser	FLDDOCUPDATEUSER	As String	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	Property	API Field Name	Return value	Field length
Public ReadOnly Property	HistoryNoteREC_ID	FLDHISRECID	As String	20
Public Property	[Date]	FLDHISNOTEDATETIME	As DateTime	N/A
Public Property	Description	FLDHISDESCRIPTION	As String	Unlimited
Public Property	RelLinkREC_ID	FLDHISLINKRECID	As String	20
Public Property	Field	FLDHISUSER1	As String	25
Public Property	About	FLDHISKIND	As String	15
Public Property	EmployeeREC_ID	FLDHISWORKERID	As String	20
Public Property	AccountREC_ID	FLDHISCARDID	As String	20
Public Property	Contact	FLDHISCONTACTID	As String	20
Public Property	DocumentREC_ID	FLDHISDOCID	As String	20
Public Property	CreatedByUser	FLDHISCREATEUSER	As String	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	Property	API Field Name	Return value	Field length
Public ReadOnly Property	ItemREC_ID	FLDITMRECID	As String	20
Public Property	ItemGroup	FLDITMITEMTYPEGROUP	As String	1
Public Property	ItemCode	FLDITMITEMNO	As String	30
Public Property	ItemName	FLDITMNAME	As String	60
Public Property	PriceSource	FLDITMPRICESOURCE	As String	1
Public Property	PricePerHour_Unit	FLDITMUNITISHOUR	As String	1
Public Property	Price	FLDITMUNITPRICE	As Double	N/A
Public Property	Cost	FLDITMSTANDARDCOST	As Double	N/A
Public Property	Tax1	FLDITMTAXCODE1	As String	3
Public Property	Tax2	FLDITMTAXCODE2	As String	3
Public Property	Tax3	FLDITMTAXCODE3	As String	3
Public Property	DescriptionByName	FLDITMDESCBYNAME	As String	1
Public Property	Description	FLDITMDESC	As String	Unlimited
Public Property	Suspend	FLDITMSUSPENDED	As String	1
Public Property	Notes	FLDITMNOTES	As String	Unlimited
Public Property	Field1	FLDITMUSER1	As String	25
Public Property	CreateUser	FLDITMCREATEUSER	As String	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	Property	API Field Name	Return value	Field length
Public ReadOnly Property	KnowledgeBaseArticleREC_ID	FLDKBARECID	As String	20
Public Property	DocumentDate	FLDKBACREATEDATE	As DateTime	N/A
Public Property	Title	FLDKBATITLE	As String	250
Public Property	Problem	FLDKBAPROBLEM	As String	Unlimited
Public Property	Solution	FLDKBASOLUTION	As String	Unlimited
Public Property	Status	FLDKBASTATUS	As String	1
Public Property	Category	FLDKBACATEGORY	As String	100
Public Property	[Public]	FLDKBAISPUBLIC	As String	1
Public Property	CreatedByUser	FLDKBACREATEUSER	As String	20
Public Property	LastUpdateByUser	FLDKBAUPDATEUSER	As String	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	Property	API Field Name	Return value	Field length
Public ReadOnly Property	OpportunityREC_ID	FLDOPPRECID	As String	20
Public Property	OpportunityName	FLDOPPNAME	As String	50
Public Property	OpportunityID	FLDOPPUSERID	As String	15
Public Property	AccountREC_ID	FLDOPPCARDID	As String	20
Public Property	Source	FLDOPPSOURCE	As String	30
Public Property	CloseDate	FLDOPPCLOSEDATE	As DateTime	N/A
Public Property	Manager	FLDOPPWORKERID	As String	20
Public Property	OpenDate	FLDOPPOPENDATE	As DateTime	N/A
Public Property	CloseByDate	FLDOPPESTDATE	As DateTime	N/A
Public Property	Amount	FLDOPPAMOUNT	As Double	N/A
Public Property	Probability	FLDOPPPROBABILITY	As Double	N/A
Public Property	Stage	FLDOPPSTAGE	As String	30
Public Property	Status	FLDOPPSTATUS	As Integer	N/A
Public Property	ClosingAmount	FLDOPPCLOSEAMOUNT	As Double	N/A
Public Property	Description	FLDOPPDESCRIPTION	As String	Unlimited
Public Property	OpportunityType	FLDOPPKIND	As String	30
Public Property	OpportunityReason	FLDOPPREASON	As String	30
Public Property	Note	FLDOPPNOTES	As String	Unlimited
Public Property	Territory	FLDOPPREGION	As String	30
Public Property	Field1	FLDOPPUSER1	As String	30
Public Property	Field2	FLDOPPUSER2	As String	30
Public Property	Field3	FLDOPPUSER3	As String	30
Public Property	CreatedByUser	FLDOPPCREATEUSER	As String	20
Public Property	LastUpdateByUser	FLDOPPUPDATEUSER	As String	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	Boolean	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	Boolean	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(Of KeyValuePair(Of String, String))	No	Not used, reserved for future use
RaiseExceptionIfDatabaseFieldTruncated	Boolean	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	Boolean	12 hour or 24 hour time format.

Table below list the CommitCRM.Application methods.

Access modifier	Method	Arguments	Return value	Description
Public Shared Function	instance	()	Application	Method that returns the singleton object. Use it to access all CommitCRM.Application properties/methods.
Public Shared Sub	Initialize	(ByVal c As Config)		Method that initializes the internal CommitCRM API DLLs. Must be the first call before using any other CommitCRM library calls.
Public Shared Sub	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	Integer	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:

Dim ticketSearch As New CommitCRM.ObjectQuery(Of 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"))
Dim tickets As List(Of CommitCRM.Ticket) = 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	Method	Arguments	Return value	Description
Public Sub	AddCriteria	(ByVal sField As String, ByVal opEnum As OperatorEnum, ByVal sValue As String)		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 Sub	AddCriteria	(ByVal field As CmtField, ByVal opEnum As OperatorEnum, ByVal sValue As String)		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 Sub	AddCriteria	(ByVal field As CmtField, ByVal opEnum As OperatorEnum, ByVal dtValue As DateTime)		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 Sub	AddCriteria	(ByVal field As CmtField, ByVal opEnum As OperatorEnum, ByVal nValue As Integer)		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 Sub	AddCriteria	(ByVal field As CmtField, ByVal opEnum As OperatorEnum, ByVal nValue As Double)		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 Sub	AddSortExpression	(ByVal sField As String, ByVal sortEnum As SortDirectionEnum)		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 Sub	AddSortExpression	(ByVal field As CmtField, ByVal sortEnum As SortDirectionEnum)		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 Function	FetchObjects	()	As List(Of T)	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:

Dim config As New CommitCRM.Config
config.AppName = "VB.NET 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)

Dim account As 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