API Code Samples: Difference between revisions

From RangerMSP Wiki - PSA software for MSPs and IT services providers
Jump to navigation Jump to search
Line 167: Line 167:
#Add ;
#Add ;
#Add the path to the folder: <server>\Commit\ThirdParty\UserDev\ and confirm.
#Add the path to the folder: <server>\Commit\ThirdParty\UserDev\ and confirm.


For all field description see the [[API Reference Manual]].
For all field description see the [[API Reference Manual]].


  Private Declare Sub CmtInitDbEngDll Lib "C:\DemoVBA\CmtDbEng.dll" (ByVal xSoftWareName As String, _
  Private Declare Sub CmtInitDbEngDll Lib "C:\DemoVBA\CmtDbEng.dll" (ByVal xSoftWareName As String, _

Revision as of 09:31, 20 August 2009

User Manuals > API Developers Guide > API Code Samples

The Commit API allows you to add/update the following entities:

  • Accounts
  • Assets
  • Tickets
  • Charges
  • Appointments
  • Tasks
  • History Notes
  • Opportunities
  • Documents
  • Knowledge Base Articles

Each API method requires a list of parameters which contain the field names and their values. The field names are the Database field names. You can see each field's name within the application (so you can verify which field you are about to update), by right-clicking the field and selecting Field Settings > Advanced Tab > view the Tech. Rec ID field.

You can view the complete list of database fields in the API Reference Manual above.

Following are samples for using the API by Email and the Programming API. The samples are basic and provide an easy starting point.

Code samples

The following code samples demonstrate how to add and update a record in CommitCRM from VBA, C++ or Delphi programs.

Make sure to read Using Commit API before going through the samples, as it provides an overview of the Commit API work-flow and how it should be used.

To test samples, it is recommended that you download a trial version of CommitCRM from our web site and install it on a new computer that is not running CommitCRM. Then, modify the paths in the source code to point to folder <testcomputer>\Commit\LastVer (and to the same files it already points to).

When developing your programs please make sure you work under the <testcomputer>\Commit\ThirdParty\UserDev folder (or at least call the dlls in this location). Do not copy the dll’s to any other location.

These samples create a connection to CommitCRM's database, add a new Account record into the database, and update it. Each transaction should specify the database table to be updated by the transaction:

Application entity Table name Code
Accounts Cards 10
Opportunities Opps 20
Documents Docs 30
Charges Docs 30
Charges Slips 40
Appointments/Tasks Events 50
History Notes Notebook 60
Tickets Tickets 70
Items Items 80
Assets Assets 90
Knowledge Base KBArticles 100

API functions

The Programming API provides the following API functions:

Method Return Value Description
CmtInitDbEngDll (app_name, path, status) status (int) Establishes a connection to the database. app_name - This string will be used for all functions of the package, and will appear in the application as the user who performs the changes in the records you update. You should specify a meaningful value. path - The path to the DB folder where the Commit server is installed: <server>\Commit\Db status - 1 for success. See Error Codes Description for other values.
CmtInsUpdRec(data_buff, map_buff, flag, tbd,

rec_id_buff_size, error_codes_buff_size,
err_msg_buff_size,rec_id_buff,
err_codes_buff, err_msg_buff, status)

status (int), rec_id (char) Adds/Updates records.

data_buff - string containing the values to insert into the Database
map_buff - mapping of the database fields corresponding with the data buff
flag - stop(0)/continue(1) the input process is an invalid data value(s)
tbd - Not used
rec_id_buff_size - length of REC ID Buffer
err_code_buff_size - length of Error Code Buffer
err_msg_buff_size - length of Error Message Buffer
rec_id_buff - buffer for returned REC ID
err_codes_buff - buffer for returned Error Codes
err_msg_buff - buffer for returned Error Messages
status - returned status, 1 for success.
See Error Codes Description for other values.

CmtTerminateDbEngDll Close the connection to the database
CmtGetDescriptionByCode (code,
desc_size,
desc) 		message (char) Call this function in case of error in

CmtInsUpdRec.
In case of error (return code other than 1),
you can use this to get error string.

CmtGetDescriptionByStatus Call this function in case of error in

CmtInitDbEngDll

Field buffers The record to be added/updated in the database is passed to the Commit API in two buffers:

Parameter Description Example
data_buff String containing the values to insert into the Database. Separators between the fields are defined in the map_buff "17/04/2008 14:44", "CRD7C9KZPS9JN3LEZVD9", "Charge", "CRDGO0SVQ6074CMAN7DW","Closed","test note in DB Engine", "NTBL6PDPKUU6NXLRHLHP","CRDBSMJ3P72EHMU0HB LX","TKT4S81466E05IM8P23X"
map_buff Mapping of the data_buff: separators, field names.

Field names must be in the same order as the data_buff values.

The field names should be separated with a different separator than the values (e.g. "new line").

" , FLDHISNOTEDATETIME

FLDHISWORKERID
FLDHISKIND
FLDHISCONTACTID
FLDHISUSER1
FLDHISDESCRIPTION
FLDHISRECID
FLDHISCARDID
FLDHISLINKRECID

VB Sample

To test the following VB code, create a VB program that includes this code and executes it, or open the Visual Basic editor included with MS-Word, paste the code into it and run it.

In order for the VB sample to compile properly, please follow these steps:

  1. Go to My Computer > Right Click – Properties > Advanced Tab > Environment Variable
  2. At the bottom of the list, search for the Path variable (not PathText)
  3. Double click the Path variable > go to the end of the value/line
  4. Add ;
  5. Add the path to the folder: <server>\Commit\ThirdParty\UserDev\ and confirm.


For all field description see the API Reference Manual. 

Private Declare Sub CmtInitDbEngDll Lib "C:\DemoVBA\CmtDbEng.dll" (ByVal xSoftWareName As String, _
  ByVal xDbPath As String, ByRef xvStatus As Integer)
  
Private Declare Sub InitCommonControls Lib "comctl32.dll" ()
  
Private Declare Sub CmtInsUpdRec Lib "C:\DemoVBA\CmtDbEng.dll" (ByVal xSoftWareName As String, _
 ByVal xDataKind As Integer, _
 ByVal xDataBuff As String, _
 ByVal xMapBuff As String, _
 ByVal xContWhenInvalidData As Integer, _
 ByVal xFlags As Integer, _
 ByVal xRecIDBuffLen As Integer, _
 ByVal xLogErrCodesBuffLen As Integer, _
 ByVal xLogErrMsgBuffLen As Integer, _
 ByVal xvRecIDBuff As String, _
 ByVal xvErrCodesLogBuff As String, _
 ByVal xvErrMsgLogBuff As String, _
 ByRef xvStatus As Integer)
 
  Private Const C_DataBuffSize  As Integer = 1024
  Private Const C_MapBufSize  As Integer = 1024
  Private Const C_ErrMsgBuffSize  As Integer = 1024
  Private Const C_ErrCodeBuffSize  As Integer = 64
  Private Const C_RecIDBuffSize  As Integer = 20
  Private Const C_Flag  As Integer = 1
  Private Const C_Ok  As Integer = 1
  Private Const C_AccountsTable  As Integer = 10
  
  Private Const C_AppName As String = "Demo"
  
Public Sub DBEng()
 
  Dim nStatus As Integer
  Dim l As Long
  Dim S As String
  Dim pStr As Long
  Dim MapBuff As String
  Dim DataBuff As String
  Dim RecIdBuff As String * C_RecIDBuffSize
  Dim ErrCodesLogBuff As String * C_ErrCodeBuffSize
  Dim ErrMsgLogBuff As String * C_ErrMsgBuffSize
   
  Call CmtInitDbEngDll(C_AppName, "C:\DemoVBA\DB\", nStatus)
   
  If nStatus = C_Ok Then
   
Rem  ******************** Establishing connection with Commit, Should be 
    called only once for the entire session ******
    MapBuff = "'" + Chr(13) + "," + Chr(13) + "FLDCRDFULLNAME" + Chr(13) + "FLDCRDDEAR" +
    Chr(13) + "FLDCRDCONTACT"
    DataBuff = "'Bart De Hantsetters','De Hantsetters','Hantsetters'"
  
    Call CmtInsUpdRec(C_AccountsTable, _
                 C_AccountsTable, _
                 DataBuff, _
                 MapBuff, _
                 C_Flag, _
                 0, _
                 C_RecIDBuffSize, _
                 C_ErrCodeBuffSize, _
                 C_ErrMsgBuffSize, _
                 RecIdBuff, _
                 ErrCodesLogBuff, _
                 ErrMsgLogBuff, _
                 nStatus)
                 
    If (ErrMsgBuff <> "") Then MsgBox ("Error Message: " + ErrMsgBuff)
    
    If nStatus = C_Ok Then
Rem      ******************** Updating the Account record we've just created *******************
    
      MapBuff = "'" + Chr(13) + "," + Chr(13) + "FLDCRDDEAR" + Chr(13) + "FLDCRDRECID"
      DataBuff = "'Doctor','" + RecIdBuff + "'"
      ErrCodesBuff = ""
      ErrMsgBuff = ""
      
      
      Call CmtInsUpdRec(C_AccountsTable, _
                 C_AccountsTable, _
                 DataBuff, _
                 MapBuff, _
                 C_Flag, _
                 0, _
                 C_RecIDBuffSize, _
                 C_ErrCodeBuffSize, _
                 C_ErrMsgBuffSize, _
                 RecIdBuff, _
                 ErrCodesLogBuff, _
                 ErrMsgLogBuff, _
                 nStatus)
      If (ErrMsgBuff <> "") Then MsgBox ("Error Message: " + ErrMsgBuff)
    
  Else
    MsgBox ("Insert new Account. Error code: " + ErrCodesLogBuff)
    
  End If
  Else
    MsgBox ("Commit Init failed. Error code: " + ErrCodesLogBuff)
  End If
   
  
End Sub

C++ Sample

// Demo.cpp : Defines the entry point for the console application.
//
#include "stdafx.h"
#include "CmtDBEng.h"
#include <string.h>
#include <stdlib.h>
int ErrCodesParsing (char* ErrCodeBuff)
{
// Demo.cpp : Defines the entry point for the console application.
//
#include "stdafx.h"
#include "CmtDBEng.h"
#include <string.h>
#include <stdlib.h>
int ErrCodesParsing (char* ErrCodeBuff)
{
 const int C_DescSize = 1024;
 char desc[C_DescSize];
 char Delimiter[] = "\n";
 int Code;
 char* pch;
 pch = strtok (ErrCodeBuff,Delimiter);
 while (pch != NULL)
 {
   Code = atoi(pch);
        CmtGetDescriptionByCode(Code, C_DescSize, desc);
   printf ("%s\n",desc);
   pch = strtok (NULL, Delimiter);
 }
 return 0;
}
int main(int argc, char* argv[])
{
 const int C_DataBuffSize = 1024;
 const int C_MapBufSize = 1024;
 const int C_ErrMsgBuffSize = 1024;
 const int C_ErrCodeBuffSize = 64;
 const int C_RecIDBuffSize = 64;
 const int C_Flag = 1;
 const int C_Ok = 1;
 const int C_AccountsTable = 10;
 const int C_ExampleCode = 54000;
 int Status;
 char DataBuff[C_DataBuffSize] = "";
 char MapBuff[C_MapBufSize] = "";
 char RecIdBuff[C_RecIDBuffSize];
 char ErrCodesBuff[C_ErrCodeBuffSize];
 char ErrMsgBuff[C_ErrMsgBuffSize];
 char* C_AppName = "Demo";
  
 //* Establishing connection with CommitCRM, Should be called only once for the entire session **
  
 CmtInitDbEngDll(C_AppName, // Your application name. This will be used for all functions of the
                            // package. 
 // Specify a meaningful value.
       "C:\\Demo\\DB\\", //Path to the database folder where CommitCRM the server is
                         // installed <server>\Commit\Db
  &Status);           //Returned connection status
  
 if (Status == C_Ok) {
 
  //***Insert New Account into that Accounts table *******************
  strcpy (DataBuff,"'Bart De Hantsetters','De Hantsetters','Hantsetters'");
  strcat (MapBuff, "'\n,\nFLDCRDFULLNAME\nFLDCRDDEAR\nFLDCRDCONTACT");
  strcat (RecIdBuff, "");
  strcat (ErrCodesBuff, "");
  strcat (ErrMsgBuff, "");
 
  CmtInsUpdRec(C_AppName,     //String for your selection.
               C_AccountsTable,    //Desired Table Code
               DataBuff,  //This string contains the values which we want to add to the database
               MapBuff,  //List of database fields where we want to add data
               C_Flag,//Flag - stop(0) continue(1) the input process is data 
                         //value(s) is invalid
               0,                        //Not used
               C_RecIDBuffSize,    //Length of REC ID Buffer
               C_ErrCodeBuffSize, //Length of Error Code Buffer
               C_ErrMsgBuffSize,  //Length of Error Message Buffer
               RecIdBuff,            //Buffer for returned REC ID
               ErrCodesBuff,        //Buffer for returned Error Codes
               ErrMsgBuff,           //Bufer for returned Error Messages
               &Status               //Returned status
       );
 
  if (ErrMsgBuff == "")
  printf("Error Message: %s", ErrMsgBuff);
 
  ErrCodesParsing(ErrCodesBuff);
 
  if (Status == C_Ok) {
 
     //***** Updating the Account record we've just created *************
     strcpy (MapBuff, "'\n,\nFLDCRDDEAR\nFLDCRDRECID"); // Map file for the  update 
     // transaction - the Dear field and the record id
     strcpy (DataBuff,"'Doctor','");
     strcat (DataBuff, RecIdBuff);
     strcat (DataBuff, "'");
     strcat (ErrCodesBuff, "");
     strcat (ErrMsgBuff, "");
 
 
     CmtInsUpdRec(C_AppName,    // string for your selection.
                  C_AccountsTable,    // Desired Table Code
                  DataBuff,   // string contains the values, which we want to add into the Database
                  MapBuff,    // list of the Database Fields in which we want to add data
                  C_Flag,     // Flag - stop(0)/continue(1) the input process is some data
                              // value(s) is invalid
                  0,                         // Not used
                  C_RecIDBuffSize,     // length of RecID Buffer
                  C_ErrCodeBuffSize,  // length of Error Code Buffer
                  C_ErrMsgBuffSize,   // length of Error Message Buffer
                  RecIdBuff,             // buffer for returned RecID
                  ErrCodesBuff,         // buffer for returned Error Codes
                  ErrMsgBuff,            // bufer for returned Error Messages
                  &Status                // returned status
         );
 
     if (ErrMsgBuff == "")
       printf("Error Message: %s", ErrMsgBuff);
 
     ErrCodesParsing(ErrCodesBuff);
   }
   else
   {
      printf("Insert new Account. Error code: %d\n", Status);
  	};
 
   //****Terminate connection with CommitCRM*******************
   CmtTerminateDbEngDll();
 }
 else
 {
   printf("Commit Init failed. Error code: %d\n", Status);
 };
 
 	return 0;
}

Delphi Sample

program Demo;
  
{$APPTYPE CONSOLE}
  
uses
 SysUtils, Classes;
const
 C_DataBuffSize = 1024;
 C_MapBufSize = 1024;
 C_ErrMsgBuffSize = 1024;
 C_DescSize = 1024;
 C_ErrCodeBuffSize = 64;
 C_RecIDBuffSize = 64;
  
 C_Flag = 1;
 C_Ok = 1;
 C_AccountsTable = 10;
 C_AppName = 'Demo';
  
 CmtDbEngDll = 'CmtDbEng.DLL';
  
var
 Status: integer;
 DataBuff: array [0..C_DataBuffSize] of Char;
 MapBuff: array [0..C_MapBufSize] of Char;
 RecIdBuff: array [0..C_RecIDBuffSize] of Char;
 ErrCodesBuff: array [0..C_ErrCodeBuffSize] of Char;
 ErrMsgBuff: array [0..C_ErrMsgBuffSize] of Char;
 s: string;
  
//** Establishing connection with CommitCRM, Should be called only once for the entire session *
Procedure CmtInitDbEngDll (
             xSoftWareName   : PChar; // Your application name. Once selected this  string 
                                      // will be used for all
                                      // functions of the package. Specify a meaningful value.
             xDbPath         : PChar; // Path to the DB folder under where Commit server is 
                                      // installed <server>\Commit\Db
  
             var xvStatus     : integer           // Returned connection status
            ); stdcall; external CmtDbEngDll;
  
//**** Insert/Update record
Procedure CmtInsUpdRec(
             xSoftWareName   : pChar;            // See above
             xDataKind           : integer;      // Desired Table Code
             xDataBuff           : pChar;        // String containing the values, which we want
                                                 // to add into the Database
             xMapBuff            : pChar;        // List of the database fields into 
                                                 //which we want to add data
             xContWhenInvalidData : Integer;     //Flag - stop(0)/continue(1) the input process
                                                 // is some data value(s) is invalid
             xFlags                : Integer;              // Not used
             xRecIDBuffLen      : Integer;          // Length of REC ID Buffer
             xLogErrCodesBuffLen  : Integer;  // Length of Error Code Buffer
             xLogErrMsgBuffLen     : Integer;     // Length of Error Message Buffer
             xvRecIDBuff          : pChar;            // Buffer for returned REC ID
             xvErrCodesLogBuff : pChar;         // Buffer for returned Error Codes
             xvErrMsgLogBuff    : pChar;         // Buffer for returned Error Messages
              var xvStatus       : Integer          // Returned status
             ); stdcall; external CmtDbEngDll;
  
//**** Terminate connection with CommitCRM ****
procedure CmtTerminateDbEngDll; stdcall; external CmtDbEngDll;
   
procedure CmtGetDescriptionByCode(
                                 xCode     : Integer;
                                 xDescLen  : Integer;
                                 xvDesc    : pChar); stdcall; external CmtDbEngDll;
  
procedure CmtGetDescriptionByStatus(
                                   xCode     : Integer;
                                   xDescLen  : Integer;
                                   xvDesc    : pChar); stdcall; external CmtDbEngDll;
  
procedure ErrCodesParsing (ErrCodeBuff: string);
var
 lList: TStringList;
 i: integer;
 aDescErrCode : Pchar;
begin
 try
   lList := TStringList.Create;
   lList.Text := ErrCodeBuff;
   GetMem(aDescErrCode,C_DescSize);
   for i := 0 to lList.Count - 1 do
   begin
     CmtGetDescriptionByCode(StrToInt(lList[i]), C_DescSize, aDescErrCode);
     writeln('Error Code: '+lList[i]+' Desc: '+string(aDescErrCode));
   end;
 finally
   FreeMem(aDescErrCode);
   lList.Destroy;
 end;
end;
 
procedure DisplayErrStatusCode(xCode : Integer);
var
 aStatusErrCode : Pchar;
begin
 try
   GetMem(aStatusErrCode,C_DescSize);
   CmtGetDescriptionByStatus(xCode,C_DescSize, aStatusErrCode);
   writeln('Commit Init failed. Error code: '+Inttostr(xCode)+' Desc: '+string(aStatusErrCode));
 finally
   FreeMem(aStatusErrCode);
 end;
end;
  
begin
  
 //**** Establishing connection with CommitCRM, Should be called only once for the entire session 
 CmtInitDbEngDll(C_AppName, // Your application name. Once selected this string will be used 
                            // for all functions of the package. Specify a meaningful value.
  'C:\DemoDelphi\db\',                    // Path to the DB folder under where Commit server is
                                          // installed <server>\Commit\Db
  Status                   // Returned connection status
   );
   
 if Status = C_Ok then
 begin
  
   //**** Insert a new Account into the Accounts table ****
  
   s := '"Bart De Hantsetters","De Hantsetters","Hantsetters"';
   StrPCopy(DataBuff, s);
   s := '"'+#13','+#13+'FLDCRDFULLNAME'+#13+'FLDCRDDEAR'+#13+'FLDCRDCONTACT'+#0;
   StrPCopy(MapBuff, s);
  
    CmtInsUpdRec(C_AppName,         // Your application name
                 C_AccountsTable,   // Desired Table Code
                 DataBuff,          // String containing the values, which we want to add into
                                    // the Database
                 MapBuff,           // List of the Database Fields in which we want to add data
                 C_Flag,            // Flag - stop(0)/continue(1) the input process is some data
                                    // value(s) is invalid
                 0,                             // Not used
                 C_RecIDBuffSize,         // Llength of REC ID Buffer
                 C_ErrCodeBuffSize,      // Length of Error Code Buffer
                 C_ErrMsgBuffSize,       // Length of Error Message Buffer
                 RecIdBuff,                 // Buffer for returned REC ID
                 ErrCodesBuff,             // Buffer for returned Error Codes
                 ErrMsgBuff,                // Buffer for returned Error Messages
                 Status                      // Returned status
         );
  
  
  
   if (ErrMsgBuff[0] <> #0) then
     writeln('Error Message: '+ ErrMsgBuff);
  
   ErrCodesParsing(ErrCodesBuff);
  
   if Status = C_Ok then
   begin
 //**** Updating the Account record we've just created *****
  
     // Map file for the update transaction - the Dear field and the record id
     s := '"'+#13+','+#13+'FLDCRDDEAR'+#13'FLDCRDRECID';
     StrPCopy(MapBuff, s);
  
     s := '"Doctor","'+RecIdBuff+'"';
     StrPCopy(DataBuff, s);
  
     CmtInsUpdRec(C_AppName,           // Your application name
                  C_AccountsTable,     // Desired Table Code
                  DataBuff,            // String containing  the values, which we want
                                       // to add into the Database
                  MapBuff,             // List of the database fields into which we want to add
                                       //data
                  C_Flag,              // Flag - stop(0)/continue(1) the input process is some
                                       // data value(s) is invalid
                  0,                   // Not used
                  C_RecIDBuffSize,     // Length of REC ID Buffer
                  C_ErrCodeBuffSize,   // Length of Error Code Buffer
                  C_ErrMsgBuffSize,    // Length of Error Message Buffer
                  RecIdBuff,           // Buffer for returned RECID
                  ErrCodesBuff,        // Buffer for returned Error Codes
                  ErrMsgBuff,          // Buffer for returned Error Messages
                  Status               // Returned status
         );
   
     if ((ErrMsgBuff[0] <> #0)) then
       writeln('Error Message: '+ ErrMsgBuff);
  
     ErrCodesParsing(ErrCodesBuff);
  
     if Status = C_Ok then
       Writeln('Completed Successfully');
   end
   else
   begin
     try
       s := IntToStr(Status);
     except
       s := 'ill-defined';
     end;
     writeln('Insert new Account. Error code: '+ s);
   end;
  
 //**** Terminate connection with CommitCRM****
    
   CmtTerminateDbEngDll();
 end
 else
 begin
   DisplayErrStatusCode(Status);
 end;
 
 writeln(#13#10+'press Enter to quit');
 readln;
end.

XML samples

Following are samples for adding a new Ticket and a new Charge to the Commit database using XML formatted messages.

Make sure to go over the Email Connector setup guide, and perform the XML API setup steps prior to testing the XML API.

Also please read Using Commit API#Using Commit API before going through the samples, as it provides an overview of the Commit API work-flow and how it should be used.

Notes on API by Email Activation:

  • Error Handling - Should the system fail to perform the XML transaction, an error message will be sent to the email address specified in the XML.
  • Using a Password - If you wish to use a verification password for the XML transactions, define the password using the ServerConfig.exe utility. To do so, go to the XML tab, enable the API by Email option and set a password (as specified in the XML - see General XML Tokens). Make sure to set the same Password in ServerConfig and in the XML email itself.

You can read more about the ServerConfig and how to setup the API by Email configuration in the Commit Email Connector Setup guide.

General XML Tokens

The sample and table demonstrates general parameters which should be used for any XML transaction: 

<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
  <ExternalApplicationName>N-Able</ExternalApplicationName>
  <SendResponseToEmail>youremail@yourdomain.com</SendResponseToEmail>
  <Password>the-predefined-api-password</Password>
  <ReturnTransactionID>data from external application (will be returned as-is in the response) 
</ReturnTransactionID>
  <DataKind>TICKET</DataKind>
  <RecordData>
	    ... the transaction goes here ...
  </RecordData>
</CommitCRMTransaction>
Token Comment
<?xml version="1.0" ?> The XML version - Always 1.0
<?commitcrmxml version ="1.0" ?> The Commit API XML version - Always 1.0
<CommitCRMTransaction> Start and end transactions with this token (may have more than one in a single email)
<ExternalApplicationName> The sender application name, can contain any text
<SendResponseToEmail> When set with an email address, then a response email will be sent after processing this transaction by the Email Connector
<Password> Optional Password - Only emails with a password that matches the password set in the Email Connector Settings will be processed (to prevent SPAM email from being processed and added to your CommitCRM database).
<DataKind> What is the Entity you wish to create/update.

Possible values:
ACCOUNT - for Accounts
TICKET - for Tickets
CHARGE - for Charges
ITEM - for Items
APPOINTMENT-OR-TASK - for Appointments/Task
HISTORY-NOTE - For History notes
ASSET - for Assets
OPPORTUNITY - for Sales Opportunities
DOCUMENT - for Documents
KBARTICLE - for Knowledge Base articles

Adding new Ticket

In this sample, we add a new Ticket, and set some additional fields to it, such as Notes, Source, Due Date and Dispatcher flag. 

<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
  <ExternalApplicationName>N-Able</ExternalApplicationName>
  <SendResponseToEmail>youremail@yourdomain.com</SendResponseToEmail>
  <Password>the-predefined-api-password</Password>
  <ReturnTransactionID>data from external application (will be returned as-is in the response)
</ReturnTransactionID>
  <DataKind>TICKET</DataKind>
  <RecordData>
        <FLDTKTCARDID> CUSTOMER-RECORD-ID-GOES-HERE-20-CHARS </FLDTKTCARDID>
        <FLDTKTPROBLEM>ticket description...</FLDTKTPROBLEM>
        <FLDTKTSTATUS>100</FLDTKTSTATUS>
 	 <FLDTKTKIND>General</FLDTKTKIND>
	 <FLDTKTNOTES>Notes</FLDTKTNOTES>
	 <FLDTKTSOURCE>Source</FLDTKTSOURCE>
 	 <FLDTKTSCHEDLENESTIM>60</FLDTKTSCHEDLENESTIM>
 	 <FLDTKTDUEDATETIME>02/04/08</FLDTKTDUEDATETIME>
	 <FLDTKTFORDISPATCH>Y</FLDTKTFORDISPATCH>
  </RecordData>
</CommitCRMTransaction>

Adding new Charges

<?xml version="1.0" ?>
<?commitcrmxml version = "1.0" ?>
<CommitCRMTransaction>
  <ExternalApplicationName>Alert</ExternalApplicationName>
  <SendResponseToEmail>your email address for responses</SendResponseToEmail>
  <Password>12345</Password>  >> Should be the same in the ServerConfig!
  <ReturnTransactionID>data from external application (will be returned as-is in the response) 
</ReturnTransactionID>
  <DataKind>CHARGE</DataKind>
  <RecordData>
        <FLDSLPWORKERID> CRDLS71RGU747TLHTFOR   </FLDSLPWORKERID>
        <FLDSLPCARDID> CRDLQXDL43BP5YCMSGM3</FLDSLPCARDID>
        <FLDSLPITEMID>  ITM1Q3GUI05ANBQGVY8D   </FLDSLPITEMID>
        <FLDSLPDESC>  Charge Description...   </FLDSLPDESC>
        <FLDSLPQUANTITY>  10   </FLDSLPQUANTITY>
        <FLDSLPSLIPDATE>  31/01/2008   </FLDSLPSLIPDATE>
        <FLDSLPSTARTTIME>  12:06  </FLDSLPSTARTTIME>
        <FLDSLPENDTIME>  14:50  </FLDSLPENDTIME>
        <FLDSLPBCRECID>  BCTMA51KBA925J7G0V67 </FLDSLPBCRECID>
        <FLDSLPPRICE> 125.3   </FLDSLPPRICE>
        <FLDSLPADJUSTAMOUNT>  10   </FLDSLPADJUSTAMOUNT>
        <FLDSLPUSER1>  Field 1...   </FLDSLPUSER1>
  </RecordData>
</CommitCRMTransaction>


Receiving Response

When adding or updating data via the XML API, the system can send a response (if the XML transaction specifies this in the SendResponseToEmail token). The format of the XML response is as follow:

Response in case of success: 

<?xml version="1.0" ?>
<?commitcrmxml version="1.0" ?>
<CommitCRMResponse>
	<Status>SUCCESS</Status>
	<AffectedRecId>TKTN1NIQEYYQ8PBJMDAX</AffectedRecId>
	<ReturnTransactionID>data from external application (as-is)</ReturnTransactionID>
</CommitCRMResponse>

Response in case of error: 

<?xml version="1.0" ?>
<?commitcrmxml version="1.0" ?>
<CommitCRMResponse>
	<Status>FAILURE</Status>
	<AffectedRecId></AffectedRecId>
	<ReturnTransactionID>data from external application (as-is)</ReturnTransactionID>
	<ResultCodes>50109</ResultCodes>
	<ResultMessage>
	Fields with illegal values: Operation canceled. Field: Account has invalid data - 
       TKTN1NIQEYYQ8PBJMDAX
	</ResultMessage>
</CommitCRMResponse>


Token Comment
<?xml version="1.0" ?> The XML version - Always 1.0
<?commitcrmxml version ="1.0" ?> The Commit API XML version - Always 1.0
<CommitCRMResponse> The response starts and ends with this token
<Status> The transaction status. Possible values: FAILURE, SUCCESS
<SendResponseToEmail> When set with an email address, then a response email will be sent after processing this transaction by the Email Connector
<AffectedRecId> The REC ID of the entity which was added or updated when processing the transaction.
<ResultCodes>
<ResultMessage> 		In case of a failure, this will contain the error code and description. You can find more information about error codes here.

See Also

Retrieved from "https://www.rangermsp.com/w/index.php?title=API_Code_Samples&oldid=2648"