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 will show you 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
• 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'.

- 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 http://www.commitcrm.com/wiki/API_Reference_Manual for reference. With any of these objects you can:

- Search/query for objects with CommitCRM.ObjectQuery that satisfy certain criteria, - Read/display the properties of the retrieved objects - Update/save the properties of the retrieved objects - Create/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 the field name we want to look in. Refer to http://www.commitcrm.com/wiki/API_Reference_Manual#Account_Fields 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.

Or we can 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

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 prefered 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.

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

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 http://www.commitcrm.com/wiki/API_Reference_Manual#Error_Codes_Description for the description of these values.