VB.NET API

From RangerMSP Wiki - PSA software for MSPs and IT services providers
Revision as of 07:44, 9 September 2012 by Sheli (talk | contribs) (→‎Charge Class)
Jump to navigation Jump to search
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

Libraries Setup

To download, compile and setup the libraries, please refer to VB.NET API Library Setup.

Start Basic Program

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 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 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(CommitCRM.Ticket.Fields.City, 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 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): 

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.WriteLine(account.CompanyName)
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 option 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.WriteLine(account.CompanyName)
            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 ReadOnly Property 'Status FLDCRDSUBCONTSTATUS As String 1
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 FLDCRDCOUNTRY As String 20
Public Property State FLDCRDSTATE 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 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 HourlyBased FLDSLPITEMUNITISHOUR As Boolean 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


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 Property API Field Name Return value Field length
Public ReadOnly Property QuoteLineREC_ID FLDQTLRECID As String 20
Public Property QuoteREC_ID FLDQTLQUOTERECID As String 20
Public Property ItemREC_ID FLDQTLITEMRECID As String 20
Public ReadOnly Property ItemGroup FLDQTLITEMTYPEGROUP As String 1
Public Property Quantity FLDQTLQUANTITY As Double N/A
Public Property Price FLDQTLPRICE As Double N/A
Public Property DiscountMarkup FLDQTLADJUST As String 1
Public ReadOnly Property DiscountTotalAmountForCustomer FLDQTLADJAMTDIS4CUST As Double N/A
Public ReadOnly Property DiscountPercentageForCustomer FLDQTLADJPERDIS4CUST As Double N/A
Public ReadOnly Property LineTotal FLDQTLBILLTOTAL As Double N/A
Public ReadOnly Property LineTotalForCustomer FLDQTLTOTAL4CUSTOMER As Double N/A
Public ReadOnly Property LineType FLDQTLLINETYPE As String 1
Public Property LineSortOrder FLDQTLORDER As Integer N/A
Public ReadOnly Property PriceForCustomerAfterMarkup FLDQTLPRICE4CUSTOMER As Double N/A
Public Property AdjustAmount FLDQTLADJUSTAMOUNT As Double N/A
Public Property AdjustPercent FLDQTLADJUSTPERCENT As Double N/A
Public Property AdjustType FLDQTLADJUSTTYPE As String 1
Public Property Description FLDQTLDESCRIPTION As String Unlimited
Public ReadOnly Property CreatedByUser FLDQTLCREATEUSER As String 20
Public ReadOnly Property LastUpdateByUser FLDQTLUPDATEUSER As String 20
Public ReadOnly Property CreatedDate FLDQTLCREATEDATE As DateTime N/A
Public ReadOnly Property UpdateDate FLDQTLUPDATEDATE As DateTime 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 Sub SetQuoteLineItem (ByVal sItemREC_ID As String, ByVal dblQuantity As Double, ByVal dblPrice As Double) Fills the appropriate fields for inserting Item type QuoteLine.
Public Sub SetQuoteLineItemWithDiscount (ByVal sItemREC_ID As String, ByVal dblQuantity As Double, ByVal dblPrice As Double, ByVal dblDiscount As Double, ByVal bByPercent As Boolean) Fills the appropriate fields for inserting Item type QuoteLine specifying a discount.
Public Sub SetQuoteLineItemWithMarkup (ByVal sItemREC_ID As String, ByVal dblQuantity As Double, ByVal dblPrice As Double, ByVal dblMarkup As Double, ByVal bByPercent As Boolean) Fills the appropriate fields for inserting Item type QuoteLine specifying a markup.
Public Sub SetQuoteLineText (ByVal sText As String) Sets the appropriate field for inserting Text type QuoteLine.
Public Sub MoveLineAboveLine (ByVal lnAbove As QuoteLine) 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 Sub 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 Sub 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 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

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 Property API Field Name Return value Field length
Public ReadOnly Property ContactREC_ID FLDCRDRECID As String 20
Public Property ParentAccountREC_ID FLDCRDASSIGNCARDID As String 20
Public Property AccountType FLDCRDENTITYKIND As Integer N/A
Public Property CompanyName FLDCRDCOMPANY As String 60
Public Property Contact FLDCRDCONTACT As String 40
Public Property Salutation FLDCRDSUFFIX As String 20
Public Property Title FLDCRDTITLE As String
Public Property Department FLDCRDDEPARTMENT As String 35
Public Property Dear FLDCRDDEAR As String 20
Public Property LastName FLDCRDLASTNAME As String 20
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 FLDCRDCOUNTRY As String 20
Public Property Zip FLDCRDZIP As String 15
Public Property State FLDCRDSTATE As String 30
Public Property EmailAddress1 FLDCRDEMAIL1 As String 70
Public Property Phone1 FLDCRDPHONE1 As String 25
Public Property Phone2 FLDCRDPHONE2 As String 25
Public Property FaxNumber FLDCRDFAX1 As String 25
Public Property Phone1Ext FLDCRDPHNDESC1 As String 40
Public Property Phone2Ext FLDCRDPHNDESC2 As String 40
Public Property FaxNumberExt FLDCRDFAXDESC1 As String 15
Public Property SubContractCode FLDCRDSUBCODE As String 15
Public Property Birthday FLDCRDBIRTHDAY As DateTime N/A
Public Property Notes FLDCRDNOTES As String Unlimited
Public Property CreationDate FLDCRDCREATEDATE As DateTime N/A
Public Property CreatedByUser FLDCRDCREATEUSERID As String 20
Public Property LastUpdatedBy FLDCRDUPDATEUSERID 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

Retrieved from "https://www.rangermsp.com/w/index.php?title=VB.NET_API&oldid=5862"