VB.NET API

From RangerMSP Wiki - PSA software for MSPs and IT services providers
Revision as of 11:05, 28 February 2011 by Goran (talk | contribs) (→‎Asset 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

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 the field name we want to look in. Refer to 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.

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

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.

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

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.
Public Function GetFieldValue (sKey As String) As String Retrieves the value of the field passed in sKey argument.
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.

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
Public ReadOnly Property AccountREC_ID FLDCRDRECID As String
Public Property AccountManager FLDCRDASSIGNCARDID As String
Public Property CompanyName FLDCRDCOMPANY As String
Public Property Contact FLDCRDCONTACT As String
Public Property Assistant FLDCRDASSISTANT As String
Public Property ContractREC_ID FLDCRDBCRECID As String
Public Property AccountNumber FLDCRDCARDID2 As String
Public Property ID FLDCRDCARDID3 As String
Public Property PopupMessage FLDCRDCARDMESSAGE As String
Public Property AddressLine1 FLDCRDADDRESS1 As String
Public Property AddressLine2 FLDCRDADDRESS2 As String
Public Property AddressLine3 FLDCRDADDRESS3 As String
Public Property City FLDCRDCITY As String
Public Property Country FLDCRDSTATE As String
Public Property State FLDCRDCOUNTRY As String
Public Property Zip FLDCRDZIP As String
Public Property CreationDate FLDCRDCREATEDATE As String
Public Property CreatedByUser FLDCRDCREATEUSERID As String
Public Property Dear FLDCRDDEAR As String
Public Property Department FLDCRDDEPARTMENT As String
Public Property DocumentsStoreDirectory FLDCRDDOCSFOLDER As String
Public Property EmailAddress1 FLDCRDEMAIL1 As String
Public Property EmailAddress2 FLDCRDEMAIL2 As String
Public Property AccountType FLDCRDENTITYKIND As String
Public Property FaxNumber FLDCRDFAX1 As String
Public Property FaxNumberExt FLDCRDFAXDESC1 As String
Public Property FileAs FLDCRDFULLNAME As String
Public Property Type FLDCRDKIND As String
Public Property LastName FLDCRDLASTNAME As String
Public Property Notes FLDCRDNOTES As String
Public Property Field FLDCRDPERSONID As String
Public Property Phone1Ext FLDCRDPHNDESC1 As String
Public Property Phone2Ext FLDCRDPHNDESC2 As String
Public Property Phone3Ext FLDCRDPHNDESC3 As String
Public Property Phone4Ext FLDCRDPHNDESC4 As String
Public Property Phone1 FLDCRDPHONE1 As String
Public Property Phone2 FLDCRDPHONE2 As String
Public Property Phone3 FLDCRDPHONE3 As String
Public Property Phone4 FLDCRDPHONE4 As String
Public Property Region FLDCRDREGIONCODE As String
Public Property PopupMessageDisplayIndication FLDCRDSHOWMESSAGE As String
Public Property SubContractCode FLDCRDSUBCODE As String
Public Property Salutation FLDCRDSUFFIX As String
Public Property Tax1 FLDCRDTAXCODE1 As String
Public Property Tax2 FLDCRDTAXCODE2 As String
Public Property Title FLDCRDTITLE As String
Public Property LastUpdatedBy FLDCRDUPDATEUSERID As String
Public Property WebAddress1 FLDCRDURL1 As String
Public Property WebAddress2 FLDCRDURL2 As String
Public Property Status FLDCRDUSER1 As String
Public Property Field1 FLDCRDUSER2 As String
Public Property Field2 FLDCRDUSER3 As String
Public Property Field3 FLDCRDUSER4 As String
Public Property Field4 FLDCRDUSER5 As String

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
Public ReadOnly Property AssetREC_ID FLDASTRECID As String
Public Property AssetCode FLDASTASSETCODE As String
Public Property AssetType FLDASTASSETTYPE As String
Public Property AssetName FLDASTNAME As String
Public Property Status FLDASTSTATUS As String
Public Property SerialNo FLDASTSERIALNO As String
Public Property AccountREC_ID FLDASTACCRECID As String
Public Property ContactREC_ID FLDASTCONTACTRECID As String
Public Property CreatedByUser FLDASTCREATEUSER As String
Public Property PurchaseDate FLDASTCUSTPURDATE As String
Public Property PurchasedFromUs FLDASTCUSTPURFROMUS As String
Public Property PurchaseInvoice FLDASTCUSTPUROURINV As String
Public Property CustomerPO FLDASTCUSTPURPO As String
Public Property PurchasePrice FLDASTCUSTPURPRICE As String
Public Property DeliveredDate FLDASTDELIVEDATE As String
Public Property Description FLDASTDESC As String
Public Property InstalledBy FLDASTINSTALBY As String
Public Property InstalledDate FLDASTINSTALDATE As String
Public Property LicenseCodes FLDASTLICENSECODE As String
Public Property LicenseKeys FLDASTLICENSEKEY As String
Public Property LicenseNotes FLDASTLICENSENOTES As String
Public Property Location FLDASTLOCATION As String
Public Property Manufacturer FLDASTMANUFACTURER As String
Public Property MnfSerialNo FLDASTMNFSERIALNO As String
Public Property Model FLDASTMODEL As String
Public Property Notes FLDASTNOTES As String
Public Property Quantity FLDASTQUANTITY As String
Public Property LastUpdateBy FLDASTUPDATEUSER As String
Public Property Field1 FLDASTUSER1 As String
Public Property Field2 FLDASTUSER2 As String
Public Property Field3 FLDASTUSER3 As String
Public Property Field4 FLDASTUSER4 As String
Public Property Field5 FLDASTUSER5 As String
Public Property Date1 FLDASTUSERDATE1 As String
Public Property Number1 FLDASTUSERNUMBER1 As String
Public Property VendorPurchasedDate FLDASTVENDORDATEPURC As String
Public Property VendorInvoice FLDASTVENDORINVNO As String
Public Property VendorPO FLDASTVENDOROURPO As String
Public Property VendorPrice FLDASTVENDORPRICE As String
Public Property Vendor FLDASTVENDORRECID As String
Public Property VendorSerialNo FLDASTVENDORSERNO As String
Public Property VendorWarrantyExpDate FLDASTVENDORWARREXP As String
Public Property Version FLDASTVERSION As String
Public Property WarrantyLicenseExp FLDASTWARREXPDATE As String

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
Public ReadOnly Property ' As String

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
Public ReadOnly Property ' As String

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
Public ReadOnly Property ' As String

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
Public ReadOnly Property ' As String

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
Public ReadOnly Property ' As String

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
Public ReadOnly Property ' As String

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
Public ReadOnly Property ' As String

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
Public ReadOnly Property ' As String

See Also

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