CSharp API

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

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.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 Method Arguments Return value Description
public SetFieldValue (string sKey, string sValue) void 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 GetFieldValue (string sKey) string Retrieves the value of the field passed in sKey argument. Use this method to access user-defined custom fields.
public Reload () void 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 Reinit (string sID) void Same as Reload except the unique identifier is passed as argument.
public Save () void 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 AccountREC_ID FLDCRDRECID string 20
public AccountManager FLDCRDASSIGNCARDID string 20
public CompanyName FLDCRDCOMPANY string 60
public Contact FLDCRDCONTACT string 40
public Assistant FLDCRDASSISTANT string 20
public ContractREC_ID FLDCRDBCRECID string 20
public AccountNumber FLDCRDCARDID2 string 15
public ID FLDCRDCARDID3 string 15
public PopupMessage FLDCRDCARDMESSAGE string Unlimited
public AddressLine1 FLDCRDADDRESS1 string 40
public AddressLine2 FLDCRDADDRESS2 string 40
public AddressLine3 FLDCRDADDRESS3 string 40
public City FLDCRDCITY string 30
public Country FLDCRDSTATE string 20
public State FLDCRDCOUNTRY string 30
public Zip FLDCRDZIP string 15
public CreationDate FLDCRDCREATEDATE DateTime N/A
public CreatedByUser FLDCRDCREATEUSERID string 20
public Dear FLDCRDDEAR string 20
public Department FLDCRDDEPARTMENT string 35
public DocumentsStoreDirectory FLDCRDDOCSFOLDER string 100
public EmailAddress1 FLDCRDEMAIL1 string 70
public EmailAddress2 FLDCRDEMAIL2 string 70
public AccountType FLDCRDENTITYKIND int N/A
public FaxNumber FLDCRDFAX1 string 25
public FaxNumberExt FLDCRDFAXDESC1 string 15
public FileAs FLDCRDFULLNAME string 60
public Type FLDCRDKIND string 30
public LastName FLDCRDLASTNAME string 20
public Notes FLDCRDNOTES string Unlimited
public Field FLDCRDPERSONID string 20
public Phone1Ext FLDCRDPHNDESC1 string 40
public Phone2Ext FLDCRDPHNDESC2 string 40
public Phone3Ext FLDCRDPHNDESC3 string 15
public Phone4Ext FLDCRDPHNDESC4 string 15
public Phone1 FLDCRDPHONE1 string 25
public Phone2 FLDCRDPHONE2 string 25
public Phone3 FLDCRDPHONE3 string 25
public Phone4 FLDCRDPHONE4 string 25
public Region FLDCRDREGIONCODE string 15
public PopupMessageDisplayIndication FLDCRDSHOWMESSAGE string 1
public SubContractCode FLDCRDSUBCODE string 15
public Salutation FLDCRDSUFFIX string 20
public Tax1 FLDCRDTAXCODE1 string 3
public Tax2 FLDCRDTAXCODE2 string 3
public Title FLDCRDTITLE string 30
public LastUpdatedBy FLDCRDUPDATEUSERID string 20
public WebAddress1 FLDCRDURL1 string 100
public WebAddress2 FLDCRDURL2 string 100
public Status FLDCRDUSER1 string 30
public Field1 FLDCRDUSER2 string 30
public Field2 FLDCRDUSER3 string 30
public Field3 FLDCRDUSER4 string 30
public Field4 FLDCRDUSER5 string 30
Retrieved from "https://www.rangermsp.com/w/index.php?title=CSharp_API&oldid=4874"