API Developers Guide

CommitCRM provides various tools in order to read/add/update information in the Commit database. These tools include: Programming API and API by Email for updating the database, and an ODBC Link for pulling information from the database. The Commit API provides developers with a set of APIs which allow them to perform database transactions in order to add and update records in the Commit database. The API can be used as a Programming API by embedding code which uses the API functions, or as an API by Email which allows you to send XML formatted emails which will be processed and executed.

• Programming API
  The Commit API provides developers with a set of API functions which can be used in VB, C++, Delphi and any other programming language that lets you use a standard Windows dll file. It provides the ability to create a connection to Commit's database, add new records to the database and update them.
• API by Email
  The API by Email allows you to send XML formatted emails which contain database transactions. Commit Email Connector then pulls the incoming XML emails from your POP3 mail server, processes the email and performs the transactions in the XML transaction. XML formatted email gives you an API for the Commit database, which allows you to perform many actions such as linking to external systems, receiving forms submitted from your web site, and more.
• ODBC Link
  While the API provides the means for adding and updating information in the database, you should use ODBC Link in order to read information from the database. Commit uses an open database structure and allows other applications to access the database using ODBC (Open Data Base Connectivity) for read-only purposes.
  
  You can use ODBC Link in order to read data from the database and integrate it with an external system (i.e. Crystal reports, or any other application). You may also use the ODBC Link to read Database Record IDs and update existing records. This will be discussed later in this document.

Glossary

• Commit API (Application Programming Interface) - CommitCRM provides an API which allows you to add and update records in the Commit database. The API includes a list of possible actions and parameters.

• ODBC Link (Open Data Base Connectivity) - ODBC is a function library which provides a common API for ODBC compliant databases. Commit provides an open database and allows other applications to access the database using ODBC for read-only purposes.

• Record - Each entity in the Commit database (such as Ticket, Account, Asset, Item, Appointment, Task, etc.) is considered a "record".

• Database fields - Each record contains a list of fields, each of which holds the record's data.

• Transaction – All additions or updates to record in the database are done by using a transaction. Each transaction includes the operation you wish to perform, the data type you wish to add/update and the additional parameters (database fields and their values).

• Transaction Parameters - Each transaction contains the parameters for performing the transaction: record type, list of database fields and a list of the values to be updated in these fields.

• External Application - This refers to the external program which integrates with Commit in order to update the database. This name should be passed when performing updates to the database, and it will be saved in the Commit record to indicate who performed the changes.

• Record ID (REC ID) - Each record in Commit has a unique Record ID which is created when adding the record to the database. Every ID is 20 characters and should be transferred with the API transaction when you need to update an existing record.

Using Commit API

Commit API allows you to add and update records in the Commit database, such as Accounts, Tickets, Assets, Items, Appointments, Tasks and more.

The updates are performed using transactions, where each transaction includes the operation you wish to perform, the data type you wish to add/update, and any additional parameters (i.e. record type, database fields and their values).

Every record added to the system is assigned a unique Record ID (REC ID) which is the database identifier for this record.

The Commit API allows you to perform the following operations.

• Add new records - if no Record ID is passed in the transaction, the API assumes that this is a new record, adds it to the system and creates a new Record ID for it.

• Update existing records - if the record ID is passed in the transaction, and the record exists, the system will update the record with the information in the transaction.

In both cases, the system will try to set default values for fields which do not exist in the incoming transaction. If it fails, the action will fail with an error.

Note that in order to read data from the Commit database, you should use the ODBC Link, which provides a read-only link for the Commit database. See more details in Retrieving data using ODBC.

Workflow

Following is a sample work-flow, which demonstrates the process of adding a new Account, and then adding a new Ticket to this Account, using the Commit API. Note that the External Application should keep the REC ID which is returned from the API response. This allows you to later update the existing records with new data or add records related to it (such as opening a Ticket under the Account).

Updating existing records

In order to update an already existing record in the database (e.g. add a Ticket to an Account, update an Account's phone number, add a new Charge to an existing Ticket, etc.), you should pass the record's unique identifier to the API so it will update the existing record rather than create a new Account. The record's unique identifier is referred to as the Record ID (REC ID).

The Record ID can be obtained in the following ways:

1. API Response (as in the flow above) - You can extract the newly created Record ID from the Email Response when adding new records with the API. This requires the developer to process the API responses, and extract the returning REC ID for each newly added record.
2. ODBC Link - Use the ODBC Link to find relevant records (Accounts, Tickets, etc.), and read all information from the database, including the unique Record ID.
3. Manually - from the Account's Notes tab, at the bottom, right-click the REC ID field and copy it.

Once you have obtained the Record ID you can pass the Record ID as a parameter for the API and update this record.

Programming API

The Programming API allows you access the Commit database and perform transactions from within a program (using various programming language). This means you can embed code which accesses the Commit database from within your own application, and add your own functionality which updates the database.

The programming API executes database transactions. Each transaction uses API methods provides by the API dll file which is located in the Commit installation. Both the Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools needed for adding/updating information in the database. In order to retrieve data, you should use the ODBC link which allows you to connect to the database and retrieve data directly from the tables. You can read more about it in the Retrieving data using ODBC section.

You can find more information and samples in the Code samples section.

API by Email (XML transaction)

The API by Email operates under the Commit Email Connector module, which automatically processes incoming emails arriving at a defined public email address. The Email may contain XML formatted messages which contain API transactions, and provides a full API to Commit.

The Email Connector pulls incoming emails from your POP3 mail server, and processes the email. When an email containing XML formatted message is detected, the system analyzes the XML content of the email and performs the transactions written in the XML. You may set the Email Connector to send automatic replies in response to XML formatted email.

The API by Email executes database transactions. Each transaction uses API methods provided by the API dll file which is located in the Commit installation. Both the Programming API and the API by Email use the same dll for performing the transactions.

Note that the API provides the tools for adding/updating information in the database. In order to retrieve data, you should use the ODBC link which allows you to connect to the database and retrieve data directly from the tables. You can read more about it in the Retrieving data using ODBC section.

You can find more information and samples in XML samples.

Retrieving data using ODBC

Commit uses an open database and allows other applications to access it using ODBC (Open Data Base Connectivity) for read-only purposes. While the API provides the means for adding and updating information in the database, it is preferred to use ODBC to read information from the database.

You can use ODBC Link to read data from the database and integrate it with an external system (i.e. Crystal reports, or any other application). You may also use the ODBC Link in order to read the Database Record ID and update existing records (see Updating existing records).

Activation Notes:

• ODBC connection is not officially supported yet, and although ODBC itself is well tested, we do not provide "pure ODBC" support.

• NEVER use ODBC to modify or delete data; use it for READ purposes only. Modifying data should be done using the Commit API.

• The ODBC Link can be used with your installed version of Commit, and only requires installing an external driver. Before working with the API we recommend that you backup the database.

• We also suggest that the Commit application not be in use while data is being accessed with ODBC (this includes the CommitWebInterface and CommitServer services if they are in use). This may prevent data sharing issues.

Below are the database table names and their meaning:

Commit Record	Database Table Name
Accounts	Cards
Tickets	Tickets
Charges	Slips
Assets	Assets
Appointments	Events
Tasks	Events
History Notes	NoteBook
Opportunities	Opps
Documents	Docs
Knowledge Base	KBArticles

For the database fields list, please refer to API Reference Manual section. You can find detailed instructions for using the ODBC Link in the Installing ODBC Driver section.

Installing ODBC Driver

Product Overview
The Advantage ODBC Driver is an ODBC version 3 driver based on the Advantage Client Engine that provides SQL access to the Advantage Database Server. The driver provides full support for the "Minimum" ODBC SQL grammar specification, as well as many functions included in the "Core" and "Extended" grammar specifications. When used with the Advantage Database Server, ODBC users can have the application stability, performance and reduced network traffic benefits of client/server architecture.

Installation on Windows
Like other ODBC drivers, the Advantage ODBC Driver is installed and managed using the ODBC Administrator Utility. This utility works with the ODBC Driver Manager to configure ODBC data sources. At runtime, the ODBC Driver Manager works with available drivers and their configured data sources. If you have previously installed ODBC drivers, the ODBC Administrator may already be installed on your workstation. The icon for the Administrator is usually found in the Control Panel.

To install the Advantage ODBC Driver:

1. Click here to download the Advantage ODBC setup program.
2. Run the Setup program.
3. Proceed through the setup windows to complete installation.

Data Source Setup for Windows
Once the Advantage ODBC Driver is installed, a data source needs to be configured to use the Advantage ODBC Driver. The data source is an entry in the Windows Registry. When a data source is defined for the Advantage Driver, all information specific to the Advantage Driver and database files is stored under the Data Source entry in the Windows 95/98/ME/ NT/2000/2003/XP Registry.
The database files and indexes must be stored on your file server, and the Advantage Database Server must be loaded in order to access the files.

The Data Source settings may be modified at any time. Using the ODBC Administrator, you may modify the Data Source and Option settings. For specific information about the screen fields see the Data Source Setup Screen.

To Setup the Data Source:

1. From the ODBC Administrator, click Add.
2. Highlight the Advantage SQL ODBC line, and click OK.
3. Type a unique data source name. For example, type AdvData. This name is used by applications to reference the data source.
4. Specify the database or data dictionary path. Type a valid path name to a mapped drive on the server where the Advantage Database Server is installed or the path and file name of your Advantage Data Dictionary. Click Browse to select a database path or check the Data Dictionary check box and then browse to select a data dictionary file. Note Multiple Advantage data sources may need to be defined for your environment. If different settings are needed for ODBC connections in one application, separate data sources may be required.
5. Review the options and change them to your desired setup.
6. Once the Options are reviewed and/or altered, click OK to exit and save the settings. The new data source is displayed.
7. Click Close to exit the ODBC Administrator.

ODBC Data Source Entries for Windows In Microsoft Windows, the entries are registry settings found on HKEY_CURRENT_USER\Software\ODBC\ODBC.INI\ (your unique data source name) or HKEY_LOCAL_MACHINE\Software\ODBC\ODBC.INI (your unique data source name). Unless specified otherwise, all registry entries can be setup by the Advantage ODBC Driver setup utility. See Data Source Setup for Windows and Data Source Setup Screen for more information.

ODBC Data Source Keys The following ODBC registry is required for the driver to load: