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

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 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:

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 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 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.FileAs, CommitCRM.OperatorEnum.opEqual, "New York");